Lists and list items
Material list rows with passive, action, single-selection, and multiple-selection semantics kept explicitly distinct.
List items organize related content into Material rows. The same visual family can represent passive content, an action, one-of-many selection, or independent multiple selection; those browser contracts must remain distinct.
import { ListItem } from '@m3-ui/ui';
<ListItem supportingText="Last synced 2 minutes ago">
Material library
</ListItem>When to use
Use list items for repeated rows with a shared content hierarchy. Do not turn every row into a button merely because it is clickable-looking; choose passive, action, or selection semantics from what activation actually means.
Use native links for navigation when browser link behavior is required rather than modeling document navigation as a button action.
Anatomy and line count
overline and supportingText determine one-, two-, or three-line Material arrangements, with lineCount available when the public composition needs an explicit line family. leading and trailing are visual slots; they should not become hidden duplicate controls.
Passive and action rows
A passive ListItem is content only. Supplying onPress opts into the React Aria-backed button path with hover, press, focus-visible, ripple, and disabled behavior.
<ListItem onPress={openDetails} supportingText="View details">
Release notes
</ListItem>Do not nest independent interactive controls inside an action row in a way that creates invalid nested interaction.
Segmented lists
Use SegmentedListItemGroup when passive, action, or independently checkable rows should use the expressive segmented list treatment. The group owns the canonical 2px spacing and first/middle/last/only base geometry; each child is still the same ListItem semantic engine.
<SegmentedListItemGroup>
<ListItem onPress={openProfile}>Profile</ListItem>
<ListItem
selectionMode="multiple"
selected={notifications}
onSelectionChange={setNotifications}
>
Notifications
</ListItem>
</SegmentedListItemGroup>For one-of-many selection, use ListItemSelectionGroup variant="segmented". It keeps the existing radiogroup and roving-focus contract while applying the same segmented geometry.
The positional shape is only the idle base shape. Hover, focus, press, selected, and dragged Material states replace it with their reviewed full state shape rather than preserving first/last outer corners.
Single selection
selectionMode="single" exposes radio-item semantics. Related rows belong in ListItemSelectionGroup, which provides the group relationship and one-of-many keyboard/focus behavior. Set variant="segmented" when the same radio group should use expressive segmented geometry.
Single selection is not an ordinary action button and not an independent checkbox.
Multiple selection
selectionMode="multiple" exposes checkbox semantics and independent selected state. Multiple-selection rows do not use the single-selection roving-focus contract.
Keep each selected state application-controlled/uncontrolled through the documented public API instead of styling selected rows directly.
Drag presentation
isDragged is a Material visual state only. It does not implement HTML drag-and-drop, pointer reordering, data transfer, or application sorting by itself.
Accessibility
Choose the semantic mode that matches the row's real behavior. Keep leading/trailing decorative content from becoming duplicate accessible names, and use real links when navigation semantics are needed.
For selectable rows, preserve the radio vs checkbox distinction. For action rows, ensure the whole action has a clear accessible name and avoid nested interactive descendants.
API reference
ListItem
ListItem(props: ListItemProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-label | string | undefined | — | — | @m3-ui/ui |
children* | ReactNode | — | — | @m3-ui/ui |
className | string | undefined | — | — | @m3-ui/ui |
data-testid | string | undefined | — | — | @m3-ui/ui |
isDisabled | boolean | undefined | — | — | @m3-ui/ui |
isDragged | boolean | undefined | — | — | @m3-ui/ui |
leading | ReactNode | — | — | @m3-ui/ui |
lineCount | ListItemLineCount | undefined | — | — | @m3-ui/ui |
onPress | ((e: PressEvent) => void) | undefined | — | — | @m3-ui/ui |
onSelectionChange | ((selected: boolean) => void) | undefined | — | — | @m3-ui/ui |
overline | ReactNode | — | — | @m3-ui/ui |
selected | boolean | undefined | — | — | @m3-ui/ui |
selectionMode | "single" | "multiple" | undefined | — | — | @m3-ui/ui |
style | CSSProperties | undefined | — | — | @m3-ui/ui |
supportingText | ReactNode | — | — | @m3-ui/ui |
trailing | ReactNode | — | — | @m3-ui/ui |
Source: packages/ui/src/components/ListItem/ListItem.tsx:179
Material fidelity and web adaptation
- Family
- Lists
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- ListItem · SegmentedListItem · ListItemDefaults.segmentedShapes
- Visual fidelity
- aligned: Reviewed standard and segmented ListItem geometry, positional shapes, state shapes, spacing, and Material roles are covered by canonical tokens and browser evidence.
- Behavior fidelity
- adapted: Passive rows remain div content; action rows use React Aria Button semantics. Single-selection rows expose radio semantics and an optional roving-focus ListItemSelectionGroup, while multiple-selection rows expose checkbox semantics. Segmented grouping is presentation-only: DOM position determines the idle base corners, while hover/focus/press/selected/dragged states still replace the full shape. Dragged state does not implement browser drag-and-drop by itself.
- Semantics fidelity
- adapted: Passive rows remain div content; action rows use React Aria Button semantics. Single-selection rows expose radio semantics and an optional roving-focus ListItemSelectionGroup, while multiple-selection rows expose checkbox semantics. Segmented grouping is presentation-only: DOM position determines the idle base corners, while hover/focus/press/selected/dragged states still replace the full shape. Dragged state does not implement browser drag-and-drop by itself.
- Adaptations
- Passive rows remain div content; action rows use React Aria Button semantics. Single-selection rows expose radio semantics and an optional roving-focus ListItemSelectionGroup, while multiple-selection rows expose checkbox semantics. Segmented grouping is presentation-only: DOM position determines the idle base corners, while hover/focus/press/selected/dragged states still replace the full shape. Dragged state does not implement browser drag-and-drop by itself.
Material supplies row anatomy, line families, segmented positional geometry, state presentation, and visual selection/action treatment. Browser semantics intentionally map action rows to buttons, single selection to radios, and multiple selection to checkboxes. Segmented grouping changes presentation only; it does not create a new interaction model.
Related components
- Menus — temporary action/choice lists.
- Checkbox and Radio button — explicit selection controls.
- Divider — semantic separation between content regions when appropriate.