List
A card of clickable rows, like recent projects or suggested tasks, with an optional heading, sections and footer.
List builds the card and ListItem builds each row.
Basic
List.Root is a card. Inside it, compose List.Header, List.Body and List.Footer yourself, with a List.Divider wherever you want a line. Rows go in List.Items, which renders a ul.
Each row is a ListItem.Root around one ListItem.PrimaryAction. The primary action is a button by default; pass asChild and a link to make the row navigate. ListItem.Content lays out the icon, title, description and trailing metadata inside it. Long titles truncate and show the full text in a tooltip.
Pass keyboardNavigation to let ArrowDown and ArrowUp move focus between rows. Tab still moves through every row and control in order. The list doesn't label itself: give the header a titleId and point the surrounding section at it with aria-labelledby.
Row actions
Put controls that do something other than open the row, like archiving, in ListItem.Actions. It sits beside the primary action rather than inside it, so the two never nest. Never put links or buttons in ListItem.Content, because everything in it belongs to the primary action.
Use titleBehavior="wrap" when the whole title matters, like a task name. Pass controls for the whole list to actions on List.Header. Show an empty or loading state directly in List.Body, not as a fake row. Archive every task here to see the empty state.
Suggested tasks
Sections
Group rows with List.Section, a List.Subheader and their own List.Items. Give each subheader an id and label its section with aria-labelledby. Put dividers between sections, never inside a List.Items.
The status slot holds a short label such as a Badge. A disabled primary action dims its row, and arrow keys skip it.
Reports
Today
Earlier this week
Action hint
ListItem.Reveal shows its resting content until the row is hovered with a mouse or focused with the keyboard, then swaps in active. Both take the same space, so the row doesn't shift. Touch screens keep the resting content. Use it for a ListItem.ActionHint that says what clicking the row does; the hint is hidden from screen readers, so the row's own label must already make sense.
List.Root Properties
Lets ArrowDown and ArrowUp move focus between enabled rows. Stops at the first and last row.
Default: false
Card surface color.
Default: 'primary'
Card padding. Header, Body and Footer already have their own spacing.
Default: 'none'
Runs before arrow key navigation. Call preventDefault() to stop it.
Additional classes for the card.
List.Header Properties
Heading text, rendered in an h2 and truncated when too long.
Id of the heading, for aria-labelledby on the surrounding section.
Controls at the end of the header.
Replaces the heading, for example with a collapsible trigger.
Additional classes for the header.
List.Divider Properties
Additional classes for the line. It is hidden from screen readers.
List.Body Properties
Rows, sections, or a loading or empty state.
Additional classes for the body.
List.Section Properties
Id of the section's List.Subheader.
A subheader and its List.Items.
List.Subheader Properties
Id that labels the section.
Section heading, rendered in an h3.
Additional classes for the heading.
List.Items Properties
ListItem.Root rows or other li elements.
Additional classes for the ul.
List.Footer Properties
Footer controls, such as a See all link.
Additional classes for the footer.
ListItem.Root Properties
Renders onto the child element instead of an li. Wrap it in an li if the child isn't one.
Default: false
One ListItem.PrimaryAction and optional ListItem.Actions.
Additional classes for the row.
ListItem.PrimaryAction Properties
Renders onto the child, usually a link with its own href, instead of a button.
Default: false
Called when the row is clicked.
Dims the row and skips it during arrow key navigation.
Default: false
Button type when asChild is false.
Default: 'button'
Additional classes for the button or link.
ListItem.Content Properties
Row title.
Secondary line under the title.
Icon or avatar before the title.
Aligns the leading slot with the title or centers it on the row.
Default: 'start'
Short label after the title, such as a Badge.
Metadata at the end of the row, such as a timestamp or ListItem.Reveal.
Truncates a long title with a tooltip, or wraps it onto more lines.
Default: 'truncate'
ListItem.Actions Properties
Aligns the controls with the title or centers them on the row.
Default: 'start'
Controls beside the primary action, like an archive button.
Additional classes for the container.
ListItem.Reveal Properties
Content shown until the row is hovered or focused.
Content shown while the row is hovered with a mouse or focused with the keyboard.
ListItem.ActionHint Properties
Short text describing the primary action. Hidden from screen readers and not clickable.
Additional classes for the hint.