List

List components display a collection of interactive items in a structured, vertically stacked format. Each item supports a rich anatomy — leading icons or images, title and subtitle text, hint text, and trailing suffixes like buttons or chips — making them ideal for navigation menus, settings panels, and data browsing.

Items are passed as an array to the list prop. Each item’s suffix uses a discriminated union (suffixType: 'button' | 'chip') to render either a Button or Chips component inline.

Usage

Loading Code Block...

Full example

A list with multiple items demonstrating icons, images, hints, button/chip suffixes, and trailing chevrons.

Loading Code Block...

Minimal example

A list with the bare minimum — just a title and subtext per item.

No IconsMinimal item

Loading Code Block...

Disabled items

Items with disabled: true are visually muted and prevent onPress callbacks from firing.

Disabled ItemYou can't click thisDisabled hint

Loading Code Block...

---

List props

Props	Default	Type	Description
list	[]	ListItem[]	Array of item objects to display. See the ListItem table below for the full object shape.
divide	true	boolean	Whether to show a horizontal divider line between items.

ListItem object

Suffix object

The suffix object uses a discriminated union keyed on suffixType. Set suffixType: 'button' to render a Button, or suffixType: 'chip' to render a Chips badge. The remaining fields on the object are then narrowed to the props of the matching component.

type Suffix =
  | ({ suffixType: "button" } & ButtonProps)
  | ({ suffixType: "chip" } & ChipsProps);

Discriminator

Props	Default	Type	Description
suffixType	-	'button' | 'chip'	Required. Determines which component renders on the trailing edge of the item. 'button' → Button component, 'chip' → Chips badge. Omit the entire `suffix` object to render nothing.

Button suffix (suffixType: 'button')

When suffixType is 'button', the rest of the object accepts every prop from the Button component. The most common ones are listed below; any native <button> attribute (type, aria-*, data-*, etc.) also flows through.

Props	Default	Type	Description
text	-	string	Button label. When `text` is provided it is rendered as the button's visible content.
variant	'default'	'default' | 'secondary' | 'ghost' | 'link'	Visual style of the button. `ghost` and `link` are most common for suffix usage since they blend into the list row.
size	'md'	'xs' | 'sm' | 'md' | 'lg' | 'xl'	Button height + padding preset. Prefer `sm` (or `xs`) inside a list to avoid inflating the row height.
icon	-	ReactNode	Optional icon rendered inside the button, positioned via `iconPosition`.
iconPosition	'left'	'left' | 'right'	Which side of the label the `icon` is rendered on.
loading	false	boolean	Renders an inline spinner in place of (or beside) the label. Useful for async suffix actions like 'Retry' or 'Send'.
loadingText	-	string	Text displayed next to the spinner while `loading` is true. Falls back to `text` when omitted.
disabled	false	boolean	Disables just the suffix button (independent of the list item's own `disabled` flag).
destructive	false	boolean	Applies destructive/danger styling. Use sparingly for destructive suffix actions (e.g. 'Remove').
isOutline	false	boolean	Renders the button with an outlined treatment instead of a filled background.
href	-	string	When provided, the suffix renders as an anchor styled like a button and navigates to the given URL on click.
onClick	-	(e: React.MouseEvent<HTMLButtonElement>) => void	Handler invoked when the suffix button is clicked. Fires independently of the list item's `onPress` — clicks on the suffix do NOT bubble to the row.
className	-	string	Additional CSS classes applied to the button. In Vue, use `class` on the suffix object.

Chip suffix (suffixType: 'chip')

When suffixType is 'chip', the rest of the object accepts every prop from the Chips component. Chips are display-only status indicators — prefer them for meta info (e.g. “New”, “3 unread”, “Beta”) rather than interactive actions.

Props	Default	Type	Description
text	-	string	Chip label. The visible content of the badge.
color	'neutral'	'neutral' | 'brand' | 'success' | 'warning' | 'info' | 'danger'	Semantic colour of the chip. Choose the token that matches the meaning of the label (e.g. `danger` for errors, `success` for completed states).
size	'sm'	'sm' | 'md' | 'lg'	Chip height + typography preset. `sm` is recommended inside a list row to keep the row height consistent.
type	'default'	'default' | 'outline'	Fill style. `default` uses a solid coloured background, `outline` uses a tinted background with a coloured border and matching text colour.
leading	-	ReactNode	Optional leading element (icon, avatar, dot) rendered before the chip text.
showClose	false	boolean	When true, renders a trailing close (×) button. Combine with `onClose` to make the chip dismissible.
onClose	-	() => void	Callback fired when the close button is clicked. Only used when `showClose` is true.
className	-	string	Additional CSS classes applied to the chip's root `<span>`.

Accessibility

• Each list item is rendered as a <button>, making it keyboard-focusable and screen-reader accessible
• Disabled items receive disabled attribute, preventing keyboard interaction and click events
• Leading images include alt attributes for screen readers
• Active items are visually distinguished with a background colour change

Best practices

Visual separation

Use divide for visual separation, especially when items have varying content lengths.

Suffix actions

Keep suffix actions contextual — use suffixType: 'button' for actions (View, Edit) and suffixType: 'chip' for status indicators (New, Active).

Interactive lists

Provide onPress callbacks for interactive lists; omit them for display-only lists.

Icon alignment

Use alignIcon: 'top' when items have multi-line content to keep the icon aligned with the title.

Excessive items

For lists longer than 20 items, consider pagination or virtualisation to maintain performance and usability.