Cloaked Design SystemOrganization / List
ListItem
A row composed from leading, text and trailing slots, with selection, progress, stat, empty and icon helpers. Public consumers import List and use List.Item; ListItem is not a separate package-root export.
Implementation previewCOMPLETE STORYBOOK REFERENCE
19 storiesEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Playground selectedOpen canvas
Example source
packages/design-system/src/components/organization/ListItem/ListItem.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A row composed from leading, text and trailing slots, with selection, progress, stat, empty and icon helpers. Public consumers import List and use List.Item; ListItem is not a separate package-root export.
Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 13 entry points · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { List } from '@cloakedinc/design-system';List.ItemListItemProps
packages/design-system/src/components/organization/ListItem/ListItem.tsx:39
| Prop | Type | Presence | Notes |
|---|---|---|---|
leading | React.ReactNode | Optional | Custom leading content (e.g. an `Avatar`, brand logo, or `List.Item.Icon` plate). |
leadingGlyph | "number" | "info" | "guard" | "arrow-left" | "arrow-right" | "arrow-up" | "arrow-down" | "chevron-down" | "chevron-up" | "chevron-left" | "chevron-right" | "caret-down" | "caret-up" | "trend-up" | "trend-down" | "collapse" | "expand" | "dropdown-collapse" | "dropdown-expand" | "close" | "clear" | "menu" | "copy" | "search" | "add" | "share" | "phone" | "sim" | "account" | "family" | "home" | "wifi" | "cart" | "vpn" | "lock" | "block" | "timer" | "check" | "send" | "filter" | "scan" | "log" | "trash" | "missed" | "call" | "voicemail" | "sms" | "email" | "data-removal" | "dark-web-monitoring" | "cloaked-pay" | "cloaked-ai" | "sms-guard" | "email-guard" | "call-guard" | "card" | "password" | "bell" | "circle-outline" | "dot" | "settings" | "clock" | "mail" | "message" | "user" | "upload" | undefined | Optional | Registered glyph rendered as a tone `IconTile` in the leading slot. |
tone | ListItemTone | undefined | Optional | Tone for the generated leading `IconTile`. |
overline | React.ReactNode | Optional | Small copy shown above the title. |
overlineTrailing | React.ReactNode | Optional | Accessory pinned to the top-right, aligned with the overline (e.g. a count badge). |
title | React.ReactNode | Required | Primary row title. |
titleLines | number | undefined | Optional | Wraps the title across up to this many lines before clamping. Defaults to single-line truncation. |
description | React.ReactNode | Optional | Secondary row copy. |
descriptionLines | number | undefined | Optional | Wraps the description across up to this many lines before clamping. Defaults to single-line truncation. |
value | React.ReactNode | Optional | Right-aligned value shown in the title row. |
tag | React.ReactNode | Optional | Tag slot shown at the trailing edge. |
statusLabel | React.ReactNode | Optional | Status text rendered through ListItem.StatusIndicator. |
statusTone | "neutral" | "info" | "success" | "warning" | "danger" | undefined | Optional | Status color treatment for statusLabel. |
trailing | React.ReactNode | Optional | Custom trailing content. |
trailingIcon | React.ReactNode | Optional | Icon slot shown after other trailing content. |
chevron | boolean | undefined | Optional | Override for the disclosure chevron. Leave unset to derive it from interaction — any pressable row shows one, except selection rows and rows with caller-owned trailing content. Pass `true` to force it on (e.g. a non-interactive row inside a pressable card), or `false` to force it off. |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
divider | boolean | undefined | Optional | Shows a bottom divider when true. |
dividerMode | ListItemDividerMode | undefined | Optional | Divider alignment. |
padding | ListItemPadding | undefined | Optional | Row padding preset. |
size | ListItemSize | undefined | Optional | Row density. `sm` renders a compact row (32px leading slot). Defaults to `md`. |
surface | "page" | "surface" | undefined | Optional | Row background on the `page | surface` scale. Defaults to `surface` (elevated card row); `page` sits flush on a page-level background. |
id | string | undefined | Optional | Optional id for the row container or interactive control. |
ariaControls | string | undefined | Optional | Id of content controlled by this row when used as a disclosure trigger. |
expanded | boolean | undefined | Optional | Expanded state announced for interactive rows. |
disabled | boolean | undefined | Optional | Dims the row and blocks presses. A disabled selection row keeps its radio/checkbox semantics so the choice stays announced — it just can't be chosen. |
onPress | (() => void) | undefined | Optional | Called when the row is pressed. |
ariaLabel | string | undefined | Optional | Accessible label for interactive rows when visible copy is not sufficient. |
haptic | HapticFeedback | undefined | Optional | Haptic feedback for interactive row presses. Defaults to `true` (`light`). |
testId | string | undefined | Optional | Test selector. Lands on the row's button when it is pressable, otherwise on the container. |
List.Item.SelectionListItemSelectionProps
packages/design-system/src/components/organization/ListItem/ListItem.tsx:46
| Prop | Type | Presence | Notes |
|---|---|---|---|
selectionMode | ListItemSelectionMode | undefined | Optional | Selection control shape.Source default: 'multiple' |
selectionPlacement | ListItemSelectionPlacement | undefined | Optional | Where the control renders; `leading` replaces the leading icon. Defaults to `trailing`.Source default: 'trailing' |
selected | boolean | undefined | Optional | Current selected state.Source default: false |
onSelectedChange | ((selected: boolean) => void) | undefined | Optional | Called with the next selected state when pressed. |
surface | "page" | "surface" | undefined | Optional | Row background on the `page | surface` scale. Defaults to `surface` (elevated card row); `page` sits flush on a page-level background. |
overline | React.ReactNode | Optional | Small copy shown above the title. |
id | string | undefined | Optional | Optional id for the row container or interactive control. |
style | React.CSSProperties | undefined | Optional | |
title | React.ReactNode | Required | Primary row title. |
leading | React.ReactNode | Optional | Custom leading content (e.g. an `Avatar`, brand logo, or `List.Item.Icon` plate). |
leadingGlyph | "number" | "info" | "guard" | "arrow-left" | "arrow-right" | "arrow-up" | "arrow-down" | "chevron-down" | "chevron-up" | "chevron-left" | "chevron-right" | "caret-down" | "caret-up" | "trend-up" | "trend-down" | "collapse" | "expand" | "dropdown-collapse" | "dropdown-expand" | "close" | "clear" | "menu" | "copy" | "search" | "add" | "share" | "phone" | "sim" | "account" | "family" | "home" | "wifi" | "cart" | "vpn" | "lock" | "block" | "timer" | "check" | "send" | "filter" | "scan" | "log" | "trash" | "missed" | "call" | "voicemail" | "sms" | "email" | "data-removal" | "dark-web-monitoring" | "cloaked-pay" | "cloaked-ai" | "sms-guard" | "email-guard" | "call-guard" | "card" | "password" | "bell" | "circle-outline" | "dot" | "settings" | "clock" | "mail" | "message" | "user" | "upload" | undefined | Optional | Registered glyph rendered as a tone `IconTile` in the leading slot. |
tone | ListItemTone | undefined | Optional | Tone for the generated leading `IconTile`. |
overlineTrailing | React.ReactNode | Optional | Accessory pinned to the top-right, aligned with the overline (e.g. a count badge). |
titleLines | number | undefined | Optional | Wraps the title across up to this many lines before clamping. Defaults to single-line truncation. |
description | React.ReactNode | Optional | Secondary row copy. |
descriptionLines | number | undefined | Optional | Wraps the description across up to this many lines before clamping. Defaults to single-line truncation. |
value | React.ReactNode | Optional | Right-aligned value shown in the title row. |
tag | React.ReactNode | Optional | Tag slot shown at the trailing edge. |
statusLabel | React.ReactNode | Optional | Status text rendered through ListItem.StatusIndicator. |
statusTone | "neutral" | "info" | "success" | "warning" | "danger" | undefined | Optional | Status color treatment for statusLabel. |
trailing | React.ReactNode | Optional | Custom trailing content. |
trailingIcon | React.ReactNode | Optional | Icon slot shown after other trailing content. |
chevron | boolean | undefined | Optional | Override for the disclosure chevron. Leave unset to derive it from interaction — any pressable row shows one, except selection rows and rows with caller-owned trailing content. Pass `true` to force it on (e.g. a non-interactive row inside a pressable card), or `false` to force it off. |
className | string | undefined | Optional | |
divider | boolean | undefined | Optional | Shows a bottom divider when true. |
dividerMode | ListItemDividerMode | undefined | Optional | Divider alignment. |
padding | ListItemPadding | undefined | Optional | Row padding preset. |
size | ListItemSize | undefined | Optional | Row density. `sm` renders a compact row (32px leading slot). Defaults to `md`. |
ariaControls | string | undefined | Optional | Id of content controlled by this row when used as a disclosure trigger. |
expanded | boolean | undefined | Optional | Expanded state announced for interactive rows. |
disabled | boolean | undefined | Optional | Dims the row and blocks presses. A disabled selection row keeps its radio/checkbox semantics so the choice stays announced — it just can't be chosen. |
ariaLabel | string | undefined | Optional | Accessible label for interactive rows when visible copy is not sufficient. |
haptic | HapticFeedback | undefined | Optional | Haptic feedback for interactive row presses. Defaults to `true` (`light`). |
testId | string | undefined | Optional | Test selector. Lands on the row's button when it is pressable, otherwise on the container. |
List.Item.ProgressListItemProgressProps
packages/design-system/src/components/organization/ListItem/ListItem.tsx:67
| Prop | Type | Presence | Notes |
|---|---|---|---|
progress | number | ListItemProgress | Required | Progress configuration rendered in the row. |
leading | React.ReactNode | Optional | Custom leading content (e.g. an `Avatar`, brand logo, or `List.Item.Icon` plate). |
leadingGlyph | "number" | "info" | "guard" | "arrow-left" | "arrow-right" | "arrow-up" | "arrow-down" | "chevron-down" | "chevron-up" | "chevron-left" | "chevron-right" | "caret-down" | "caret-up" | "trend-up" | "trend-down" | "collapse" | "expand" | "dropdown-collapse" | "dropdown-expand" | "close" | "clear" | "menu" | "copy" | "search" | "add" | "share" | "phone" | "sim" | "account" | "family" | "home" | "wifi" | "cart" | "vpn" | "lock" | "block" | "timer" | "check" | "send" | "filter" | "scan" | "log" | "trash" | "missed" | "call" | "voicemail" | "sms" | "email" | "data-removal" | "dark-web-monitoring" | "cloaked-pay" | "cloaked-ai" | "sms-guard" | "email-guard" | "call-guard" | "card" | "password" | "bell" | "circle-outline" | "dot" | "settings" | "clock" | "mail" | "message" | "user" | "upload" | undefined | Optional | Registered glyph rendered as a tone `IconTile` in the leading slot. |
tone | ListItemTone | undefined | Optional | Tone for the generated leading `IconTile`. |
overline | React.ReactNode | Optional | Small copy shown above the title. |
overlineTrailing | React.ReactNode | Optional | Accessory pinned to the top-right, aligned with the overline (e.g. a count badge). |
title | React.ReactNode | Required | Primary row title. |
titleLines | number | undefined | Optional | Wraps the title across up to this many lines before clamping. Defaults to single-line truncation. |
description | React.ReactNode | Optional | Secondary row copy. |
descriptionLines | number | undefined | Optional | Wraps the description across up to this many lines before clamping. Defaults to single-line truncation. |
value | React.ReactNode | Optional | Right-aligned value shown in the title row. |
tag | React.ReactNode | Optional | Tag slot shown at the trailing edge. |
statusLabel | React.ReactNode | Optional | Status text rendered through ListItem.StatusIndicator. |
statusTone | "neutral" | "info" | "success" | "warning" | "danger" | undefined | Optional | Status color treatment for statusLabel. |
trailing | React.ReactNode | Optional | Custom trailing content. |
trailingIcon | React.ReactNode | Optional | Icon slot shown after other trailing content. |
chevron | boolean | undefined | Optional | Override for the disclosure chevron. Leave unset to derive it from interaction — any pressable row shows one, except selection rows and rows with caller-owned trailing content. Pass `true` to force it on (e.g. a non-interactive row inside a pressable card), or `false` to force it off. |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
divider | boolean | undefined | Optional | Shows a bottom divider when true. |
dividerMode | ListItemDividerMode | undefined | Optional | Divider alignment. |
padding | ListItemPadding | undefined | Optional | Row padding preset. |
size | ListItemSize | undefined | Optional | Row density. `sm` renders a compact row (32px leading slot). Defaults to `md`. |
surface | "page" | "surface" | undefined | Optional | Row background on the `page | surface` scale. Defaults to `surface` (elevated card row); `page` sits flush on a page-level background. |
id | string | undefined | Optional | Optional id for the row container or interactive control. |
ariaControls | string | undefined | Optional | Id of content controlled by this row when used as a disclosure trigger. |
expanded | boolean | undefined | Optional | Expanded state announced for interactive rows. |
disabled | boolean | undefined | Optional | Dims the row and blocks presses. A disabled selection row keeps its radio/checkbox semantics so the choice stays announced — it just can't be chosen. |
onPress | (() => void) | undefined | Optional | Called when the row is pressed. |
ariaLabel | string | undefined | Optional | Accessible label for interactive rows when visible copy is not sufficient. |
haptic | HapticFeedback | undefined | Optional | Haptic feedback for interactive row presses. Defaults to `true` (`light`). |
testId | string | undefined | Optional | Test selector. Lands on the row's button when it is pressable, otherwise on the container. |
List.Item.StatListItemStatProps
packages/design-system/src/components/organization/ListItem/ListItemStat/ListItemStat.tsx:10
| Prop | Type | Presence | Notes |
|---|---|---|---|
label | string | Required | The key, rendered as secondary text on the left. |
value | string | number | Required | The statistic, rendered as primary text on the right. |
divider | boolean | undefined | Optional | Shows the row divider when true.Source default: true |
testId | string | undefined | Optional | Test selector; lands on the wrapper around the row and its divider. |
List.Item.EmptyListItemEmptyProps
packages/design-system/src/components/organization/ListItem/ListItemEmpty/ListItemEmpty.tsx:10
| Prop | Type | Presence | Notes |
|---|---|---|---|
message | string | Required | The empty-state copy, rendered as secondary text. |
testId | string | undefined | Optional | Test selector for the placeholder container. |
List.Item.IconListItemIconProps
packages/design-system/src/components/organization/ListItem/ListItemIcon/ListItemIcon.tsx:11
| Prop | Type | Presence | Notes |
|---|---|---|---|
children | React.ReactNode | Optional | |
initial | string | undefined | Optional | Fallback initial shown when children are absent. |
tone | ListItemTone | undefined | Optional | Tokenized icon color treatment.Source default: 'neutral' |
label | string | undefined | Optional | Accessible label for meaningful icons. |
background | string | undefined | Optional | Custom background color. |
foreground | string | undefined | Optional | Custom foreground color. |
List.Item.StatusIndicatorStatusIndicatorProps
packages/design-system/src/components/status/StatusIndicator/StatusIndicator.tsx:25
| Prop | Type | Presence | Notes |
|---|---|---|---|
children | React.ReactNode | Required | |
tone | "neutral" | "info" | "success" | "warning" | "danger" | undefined | Optional | Semantic status color for the dot; maps to the `--cds-status-*` tokens. Defaults to `neutral`.Source default: 'neutral' |
className | string | undefined | Optional | |
testId | string | undefined | Optional | Optional test selector. |
List.Item.ArrowIconRead source for the API
packages/design-system/src/components/organization/ListItem/ListItemActionIcons/ListItemActionIcons.tsx:13
List.Item.ChevronIconRead source for the API
packages/design-system/src/components/organization/ListItem/ListItemActionIcons/ListItemActionIcons.tsx:20
List.Item.CopyIconRead source for the API
packages/design-system/src/components/organization/ListItem/ListItemActionIcons/ListItemActionIcons.tsx:27
List.Item.MailIconRead source for the API
packages/design-system/src/components/organization/ListItem/ListItemActionIcons/ListItemActionIcons.tsx:34
List.Item.PhoneIconRead source for the API
packages/design-system/src/components/organization/ListItem/ListItemActionIcons/ListItemActionIcons.tsx:41
List.Item.MessageIconRead source for the API
packages/design-system/src/components/organization/ListItem/ListItemActionIcons/ListItemActionIcons.tsx:48
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A slot-first list row. Compose the base row from named slots — a leading edge (leadingGlyph +
tone, or a custom leading node), overline / title / description, and a trailing edge
(value, tag, statusLabel, or trailing / trailingIcon). Behavior comes from compound parts
rather than variant props.
Use when
The deciding choice is which compound part you reach for.
A pressable row (onPress) auto-reveals a chevron. Inside a List the container owns the
separators, so a row's own divider is ignored there.
Leading and trailing slots
A leading tone plate from leadingGlyph + tone, with a trailing value and status.
Tones
Every tone on the generated leading plate — status, brand, and product-feature.
Usage by variant
| Choice | Use when | Avoid when |
|---|---|---|
Part: List.Item | The default informational row — leading marker, text, and a trailing value/tag/status. The workhorse (most rows in the app). | Selection, progress, or key-value rows — those have dedicated parts below. |
Part: List.Item.Selection | Selectable rows — selectionMode="multiple" renders a checkbox, "single" a radio. | Titled option cards with supporting copy — use SelectionCard. |
Part: List.Item.Progress | A row carrying progress — kind of steps, ring, or bar (removal progress, multi-step tasks). | A static count — that is a plain row value. |
Part: List.Item.Stat | A key-value statistic row with an inset divider. Not currently used in app code, but the intended part for stat tables. | Rows with a leading marker or press affordance — use the base row. |
Part: List.Item.Empty | The placeholder row shown when a list has no items. | Loading states — this reads as "nothing here," not "still fetching." |
Part: List.Item.Icon | The leading tone plate, only when you need a custom leading marker. A standard row builds it for you from leadingGlyph + tone. | The common case — pass leadingGlyph + tone and let the row build the plate. |
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Row target
- Description
- Full-width row; becomes a button only when an action or selection callback exists.
- Required
- true
- Id
- leading
- Label
- Leading visual
- Description
- Custom content or a generated tone tile; leading selection replaces this slot.
- Required
- false
- Id
- body
- Label
- Text body
- Description
- Required title plus optional overline, description and inline progress.
- Required
- true
- Id
- value
- Label
- Value
- Description
- Optional right-aligned value in the title line.
- Required
- false
- Id
- trailing
- Label
- Trailing accessory
- Description
- One accessory selected by precedence, followed by a derived or explicit chevron.
- Required
- false
- Id
- separator
- Label
- Divider
- Description
- Optional row-owned hairline; List supplies container separators.
- Required
- false
- Id
- selection
- Label
- Selection mark
- Description
- Check or dot mark backed by the row interaction semantics.
- Required
- false
- Id
- progress
- Label
- Progress
- Description
- Ring at the trailing edge, or bar/steps under the copy.
- Required
- false
Allowed Design Choices
- Variants
- Row
- Label
- List.Item
- Selection
- Label
- List.Item.Selection
- Progress
- Label
- List.Item.Progress
- Stat
- Label
- List.Item.Stat
- Empty
- Label
- List.Item.Empty
- Icon
- Label
- List.Item.Icon
- Sizes
- Sm
- Label
- Compact
- Description
- 48px minimum, 8px gap and block padding.
- Md
- Label
- Default
- Description
- Content-dependent 48px, 64px or 80px minimum; progress can increase it.
- Selection Modes
- Single
- Label
- Single
- Description
- Radio semantics; pressing the selected row reports true.
- Multiple
- Label
- Multiple
- Description
- Checkbox semantics; activation reports the inverse selected state.
- Selection Placements
- Leading
- Label
- Leading
- Description
- Replaces an existing leading visual to preserve its column.
- Trailing
- Label
- Trailing
- Description
- Default; suitable for rows without a leading visual.
- Surfaces
- Page
- Label
- Page
- Surface
- Label
- Surface
- Padding
- Card
- Label
- Card
- Sheet
- Label
- Sheet
- Flush
- Label
- Flush
Variants
- Id
- row
- Label
- Base row
- Description
- Informational or pressable row composed from slots.
- Platforms
- web
- Id
- selection
- Label
- Selection row
- Description
- Use onSelectedChange with a controlled selected value. Choose single or multiple selection.
- Platforms
- web
- Id
- progress
- Label
- Progress row
- Description
- A number is shorthand for a trailing ring; a progress object chooses ring, bar or steps.
- Platforms
- web
- Id
- stat
- Label
- Statistic row
- Description
- Noninteractive label/value helper; it has its own divider prop.
- Platforms
- web
- Id
- empty
- Label
- Empty placeholder
- Description
- A centered message for an empty list, not a loading indicator.
- Platforms
- web
- Id
- icon
- Label
- Leading icon helper
- Description
- Tone plate for a custom leading node; generated leadingGlyph tiles do not need it.
- Platforms
- web
Sizes
- Id
- sm
- Label
- Compact
- Description
- Small density overrides rich-row height and removes inline inset; the container supplies spacing.
- Id
- md
- Label
- Default
- Description
- Default density grows with leading/trailing accessories, description, selection and progress.
Measurements
- Id
- base-min-height
- Label
- Base row minimum height
- Kind
- at-least
- Token
- --cds-size-48
- Value
- 48
- Unit
- px
- Applies To
- root
- Id
- rich-min-height
- Label
- Rich row minimum height
- Kind
- at-least
- Token
- --cds-size-80
- Value
- 80
- Unit
- px
- Applies To
- root
- Notes
- Applies to md rows with leading content, trailing content or description; a tag-only trailing slot does not promote the row.
- Id
- selection-min-height
- Label
- Copy-only selection minimum height
- Kind
- at-least
- Token
- --cds-size-64
- Value
- 64
- Unit
- px
- Applies To
- selection
- Notes
- For trailing selection with card padding and no description or leading slot; compact density is excluded.
- Id
- row-gap
- Label
- Default row gap
- Kind
- exact
- Token
- --cds-space-12
- Value
- 12
- Unit
- px
- Applies To
- root
- Id
- compact-gap
- Label
- Compact row gap
- Kind
- exact
- Token
- --cds-space-8
- Value
- 8
- Unit
- px
- Applies To
- root
- Id
- row-inset
- Label
- Default inline inset
- Kind
- exact
- Token
- --cds-space-20
- Value
- 20
- Unit
- px
- Applies To
- root
- Id
- selection-gap
- Label
- Trailing selection gap
- Kind
- exact
- Token
- --cds-space-24
- Value
- 24
- Unit
- px
- Applies To
- selection
- Id
- empty-min-height
- Label
- Empty placeholder minimum height
- Kind
- at-least
- Token
- --cds-size-240
- Value
- 240
- Unit
- px
- Applies To
- root
Layout
- Alignment
- Leading visual, text body and trailing accessory align centrally; the body flexes while accessories keep their width.
- Flow
- Slots run left to right; overline, title, description and inline progress stack within the body.
- Notes
- Accessory precedence is trailing, tag, status, selection, trailing progress, then trailingIcon. A chevron can follow the chosen accessory.
- Explicit value wins over a progress label. Custom leading content wins over a generated glyph tile.
- A selected leading control occupies the existing 40px md or 32px sm visual column. Use trailing selection for icon-less rows to avoid adding a column.
- List suppresses a direct List.Item divider. Compound Selection, Progress and Stat members retain their own divider; set divider=false when the container already draws separators.
Typography And Color
- Typography
- Label
- Title and value
- Description
- Use the body ramp.
- Token
- --cds-type-body-size
- Label
- Description
- Description
- Uses body-small with a local 1.2 line-height.
- Token
- --cds-type-body-small-size
- Colors
- Label
- Primary text
- Description
- Title and value.
- Token
- --cds-text-primary
- Label
- Secondary text
- Description
- Overline, description, stat label and empty message.
- Token
- --cds-text-secondary
- Label
- Default surface
- Description
- Default and selected row background.
- Token
- --cds-bg-surface
- Label
- Page surface
- Description
- Page-level row background.
- Token
- --cds-bg-page
- Label
- Divider
- Description
- Row-owned and container separators.
- Token
- --cds-divider
States
- Id
- informational
- Label
- Informational
- Description
- Without callbacks the row is not a press target.
- Id
- pressable
- Label
- Pressable
- Description
- onPress produces a button and normally a chevron; caller-owned trailing content or chevron=false suppresses the automatic chevron.
- Id
- selected
- Label
- Selected
- Description
- The host supplies selected. Single activation reports true; multiple activation reports the inverse value.
- Id
- disabled
- Label
- Disabled
- Description
- Prevents action and selection callbacks and dims the row. Disabled interactive selection still exposes its state.
- Id
- progress
- Label
- Progress
- Description
- Rings render trailing, bars and steps inline. The host owns progress updates.
- Id
- empty
- Label
- Empty
- Description
- List.Item.Empty renders its message in a centered 240px-minimum block.
Behavior
- Label
- Controlled selection
- Description
- Selection is host-owned. No callback means no row button; the helper uses a disabled, read-only form control to expose that selection state.
- Label
- Navigation and disclosure
- Description
- Base onPress is host-owned. ariaControls and expanded can describe a disclosure target but do not implement expansion.
- Label
- Separator ownership
- Description
- Use List for list structure and separator ownership. Standalone rows do not claim listitem semantics; compound members need an explicit divider decision.
- Label
- No nested interactive slots
- Description
- A pressable row is already the single control. Keep leading and trailing content noninteractive within it.
Accessibility
- Label
- Button, checkbox and radio roles
- Description
- Interactive rows are native buttons. Selection rows expose checkbox or radio role and aria-checked; their visible title labels them and their description is associated when present.
- Label
- Names and disabled state
- Description
- ariaLabel can replace visible naming when needed. Native disabled blocks keyboard and pointer activation; the selected state stays represented.
- Label
- Group behavior belongs to the host
- Description
- Single selection announces radio semantics, but this row family does not implement radio-group arrow-key movement or enforce one chosen row. The consumer must define and verify group behavior.
- Label
- Visible keyboard focus
- Description
- Interactive rows inherit the shared focus-visible outline. Its inset offset preserves the indicator within clipped list or card containers; disabled native buttons do not receive keyboard focus.
- Label
- List ownership
- Description
- List wraps content rows with role=listitem. A standalone row is a generic container or control, not a listitem by itself.
Content Adaptation
- Label
- Clamping
- Description
- Title and description default to one-line truncation. Positive titleLines and descriptionLines enable multi-line clamping; overline and value remain single-line. Value has a 46% maximum width.
- Label
- Empty versus pending
- Description
- Use Empty for a known empty result. It does not represent pending data, errors or a retry action.
- Label
- Review dense combinations
- Description
- Verify long titles, descriptions, values, tags, localized copy and large text at narrow widths. Do not combine every slot by default.
Motion Haptics
- Motion
- Label
- Press feedback
- Description
- Interactive rows use the shared fast press transform and opacity change; reduced-motion removes the transform. Progress and selection visuals use their own primitives.
- Haptics
- Label
- Action feedback
- Description
- Enabled action and selection callbacks request light feedback by default; haptic can override or disable it. Delivery depends on provider and host support.
Platform Differences
- Platforms
- ios
- android
- Description
- Native implementations and platform parity are not verified. Vue also has no local implementation.
- Rationale
- This preview was authored from the local React types, implementation, styles and documentation. Native unit, typography, interaction and accessibility mappings require platform review.