List Item

One row of content: a leading visual, a title and description, trailing meta and actions. Pressable, selectable or a link.

Stable

Web

iOS

Android

@advui/core

Source

JSX

<ListItem
  title="Privacy"
  description="Manage your privacy preferences"
  leading={<LockIcon />}
  trailing={<ChevronRightIcon />}
  onPress={open}
/>

Installation

Package

CLI (copy source)

pnpm

pnpm add @advui/core

npm

npm install @advui/core

Usage

import { ListItem } from '@advui/core'
import { ChevronRightIcon, LockIcon } from '@advui/icons'

<ListItem
  leading={<LockIcon />}
  title="Privacy"
  description="Manage your privacy preferences"
  trailing={<ChevronRightIcon />}
  onPress={openPrivacy}
/>

Examples

Settings list

A switch in a row without `onPress`, pressable rows with a chevron or a value, and a disabled row.

Preview

Code

Email notificationsReceive updates by email

Profiles with actions

Each row opens a profile; the email button beside it acts on its own.

Preview

Code

Selectable items

Toggle buttons for a multiple choice. The parent keeps the selected ids; for a single choice, keep one.

Preview

Code

Variants, sizes and colors

Style props take precedence over the variant and size; the selected fill paints over them.

Preview

Code

PlainNo surface of its own

FilledA muted surface

OutlineA card surface with a border

Small

Large

Custom colorsbackgroundColor, color and borderRadius

API reference

ListItem

The same component as `List.Item`. Inside a List it is a `listitem` and takes the List’s size and dividers; on its own it has no list role.

Prop	Type	Default	Description
`title`	`ReactNode`	—	Main line. An element is rendered as it is.
`description`	`ReactNode`	—	Muted second line.
`children`	`ReactNode`	—	Custom content in place of `title` and `description`. Use `ListItemTitle` and `ListItemDescription` for the same text styles.
`leading`	`ReactNode`	—	Before the text: an icon, Avatar, image, Checkbox or Radio. Icons are sized to the item (20px, 24px at `lg`) and muted. It never shrinks.
`trailing`	`ReactNode`	—	After the text: meta text, a Badge, a status or a chevron. At most half the row wide, so long meta wraps. Part of the pressable area: when the item has `onPress`, `href` or `selectable`, put controls in `actions` instead. On a row without them it may hold a Switch.
`actions`	`ReactNode`	—	Buttons or controls at the end, beside the pressable area rather than inside it, so they keep their own presses and keys. Give icon-only buttons an `aria-label`.
`variant`	`'plain' \| 'filled' \| 'outline'`	`'plain'`	`filled` is a muted surface, `outline` a bordered card surface. Inside a List, leave it `plain` and set the List’s `variant`.
`size`	`'sm' \| 'md' \| 'lg'`	`the List's size, or 'md'`	Padding, text and icon size. Rows are at least 44px, 48px or 56px tall and grow with wrapped text.
`divider`	`boolean`	from the List's `divided`	A line above the item. `false` turns off a divided List’s line for this item.
`onPress`	`(event) => void`	—	Makes the content one button (`<button>` on web), named by its text. Enter and Space press it.
`href`	`string`	—	The content is a link (`<a>` on web). On iOS and Android a path goes to the router registered with `setRouter`, and an absolute URL opens with the system.
`selected`	`boolean`	—	Highlights the item with a fill and an edge bar, on every variant. A pressable item is then the current one (`aria-current`, "page" for a link); with `selectable` it is the toggle state. Controlled by the parent.
`selectable`	`boolean`	`false`	Pressing toggles `selected`: a toggle button (`aria-pressed` on web, "checked" on native).
`defaultSelected`	`boolean`	`false`	Selected at first, when a `selectable` item manages its own state.
`onSelectedChange`	`(selected: boolean) => void`	—	Called with the new state, once per press, when a `selectable` item is pressed. Never while rendering or when disabled.
`disabled`	`boolean`	`false`	Blocks `onPress`, `href` and selection, dims the content and sets `aria-disabled`. `actions` and controls in `trailing` stay enabled: disable them yourself.
`color`	`ColorTokens`	`from the theme`	Color of the title, description, trailing text and icons. Pair it with a `backgroundColor`: `primarySoftForeground` on `primarySoft`.
`backgroundColor`	`ColorTokens`	from `variant`	Overrides the variant surface. The selected fill still paints over it.
`borderColor`	`ColorTokens`	from `variant`	Overrides the outline or divider color.
`borderRadius`	`RadiusTokens \| number`	`'md' (plain), 'lg' (filled, outline), none in a List`	Corner radius. Hover and selected fills follow it.
`padding`	`SpaceTokens \| number`	from `size`	Inner padding, applied inside the pressable area so it stays full size. `paddingHorizontal`, `paddingVertical` and the shorthands work too.
`gap`	`SpaceTokens \| number`	`'3'`	Space between the leading visual, the text and the trailing content.
`aria-label`	`string`	—	Replaces the name built from the text, e.g. "5 unread messages" for a row that shows "5".

ListItemTitle

The title text style, for custom `children`. Also `List.ItemTitle`.

ListItemDescription

The muted description style, for custom `children`. Also `List.ItemDescription`.

Accessibility

Without onPress, href or selectable the item is plain content: no button role, and its text is read in order.
With them, the leading visual, text and trailing content are one button or link, named by that text (or aria-label). Controls go in actions, which sit beside it, so there are no nested interactive elements and an action never presses the row.
Selected: a pressable item is the current one (aria-current="true", or "page" for a link); a selectable item is a toggle button (aria-pressed). Native announces "selected" or "checked". The highlight is a fill and an edge bar, not color alone.
Disabled: the button keeps focus, sets aria-disabled and ignores presses; a disabled link drops its href. A row without onPress has nothing to disable, so it is only dimmed.
Inside a List the item is a listitem; on its own it has no list role, which would be invalid outside a list.
Text wraps instead of truncating, and rows have a minimum height (44px or more) rather than a fixed one, so larger font sizes do not clip.

Keyboard interactions
Key	Action
`Tab`	Moves to the item (when pressable) and then to each of its actions.
`Enter / Space`	Presses the item, or toggles a `selectable` one.

Platform notes

Web

A pressable item is a <button>, or an <a> with href. actions are siblings of it.

iOS

A pressable item is one accessible button, or a link with href; VoiceOver reads all of its text. A path in href goes to the router registered with setRouter (since 0.15.0; before, href was web only).

Android

Same as iOS; a selectable item is a toggle button. Pressable items show the ripple when the config has androidRipple.

Since v0.13.0Last updated Nov 2, 2026Edit this page on GitHub

PreviousList

NextSpoiler

List Item

Installation

Usage

Examples

Settings list

Navigation list

Profiles with actions

Selectable items

Variants, sizes and colors

API reference

ListItem

ListItemTitle

ListItemDescription

Accessibility

Platform notes

Related components