Skip to content

List

A List component renders a collection of items as anchor links. Each item can display an icon and a label, making it useful for navigation menus or compact link groups.

Ready to use

Design Develop Accessibility

The List displays groups of related items in a compact, vertically stacked layout. It works as a building block inside other containers — dropdowns, modals, side panels — wherever a set of straightforward choices needs to read as one group.

Anatomy

Section titled “Anatomy”
  1. List option
  2. Leading icon
  3. Trailing icon
  4. Divider
  5. Bottom CTA

When to use it

Section titled “When to use it”

Use the List when:

  • You need to display groups of related items such as options or categories.
  • The content doesn’t need complex interaction beyond item selection or viewing.
  • A list will be embedded inside another container (dropdown menu, modal action set, side-panel selection).

Avoid the List when:

  • The content is tabular or multi-column — use a Data Table instead.

Properties

Section titled “Properties”

Type

Two types: Simple List for single-select or read-only browsing, and Multiselect which pairs each row with a checkbox and an item count. Both share the same row layout; only the leading control changes.

Leading and trailing icons

Optional icons before and after the label. The leading slot typically holds a category glyph or status indicator; the trailing slot carries chevrons, external-link hints, or an indicator for the current selection.

Scroll bar

A boolean that surfaces a visible scrollbar inside long lists. Default true for embedded contexts (dropdown menus, modals) so users know there’s more content beneath the fold.

Bottom CTA

Optional action area pinned beneath the list — used for “Apply” or “Clear” actions on multiselect filters. Default true on multiselect, off on simple lists.

Platform considerations

Section titled “Platform considerations”

Desktop

Lists typically sit inside other containers and hug the width of their parent. Keep row height consistent across rows so the scan reads as one column.

Tablet

Same behaviour as desktop. Touch targets are governed by the row height — make sure each option clears the recommended 44 px tap area.

Mobile

Lists often promote to a sheet at this size. Keep the bottom CTA reachable inside the thumb zone when the list lives in a multiselect filter.

Best practices

Section titled “Best practices”

Lists work best when presenting straightforward choices without additional metadata or complexity.

Do

Keep list item labels concise, fit each row on a single line, use clear and meaningful wording for each label, review long labels individually before truncating, and use the List only for simple, straightforward options without descriptions or metadata.

Don't

Don’t include two lines of text per item (multi-line labels break the layout), don’t truncate by default, don’t overload items with extra information like sublabels or tags unless they add meaning, don’t lean on the List for complex messages, and don’t mix very long items with very short ones — keep content harmonised.

Content guidelines

Section titled “Content guidelines”

Each label should communicate its purpose without extra detail or filler. Aim for short, scannable text that fits naturally on one line, and use parallel wording across items so the comparison reads cleanly. If an item needs more characters, evaluate it on its own merits before reaching for truncation — sometimes a rephrase or a different component is the better answer. Avoid leading articles (“The new Yaris”) so the comparison stays aligned by the meaningful keyword.