ts
| Guidance | Practices |
|---|---|
| Do | Provide a header to label the list and give context to screen readers. |
| Do | Use start and end content slots to add icons, avatars, or badges to each item. |
| Don't | Place interactive elements inside an interactive list item — it creates nested click targets and confusing focus behavior. |
| Don't | Use a list for a single item or for laying out unrelated content — lists imply a meaningful collection. |
| Don't | Mix clickable and non-clickable items in the same list without clear visual distinction. |
| Prop | Type | Description |
|---|---|---|
children | ReactNode | List items (XDSListItem components). |
density | 'compact' | 'balanced' | 'spacious' (default: 'balanced') | Spacing density for items. |
hasDividers | boolean (default: false) | Show dividers between items. |
header | ReactNode | Header content, associated with the list via aria-labelledby. |
listStyle | 'none' | 'disc' | 'decimal' | 'circle' (default: 'none') | List marker style. 'decimal' renders an <ol> element instead of <ul>. |
xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}. |
| Prop | Type | Description |
|---|---|---|
labelrequired | string | Primary text. |
description | ReactNode | Secondary content below the label. A plain string gets single-line truncation automatically; a ReactNode lets child components control their own wrapping and line-clamp behavior. |
startContent | ReactNode | Content rendered before the label area (e.g. icon, avatar). |
endContent | ReactNode | Content rendered after the label area (e.g. badge, chevron). |
onClick | (e: MouseEvent) => void | Click handler; enables the invisible button pattern. |
href | string | Link URL; enables the invisible anchor pattern. |
target | string | Link target attribute, only applicable when href is provided. |
isDisabled | boolean (default: false) | Disabled state; sets aria-disabled on the item. |
isSelected | boolean (default: false) | Selected state; sets aria-selected on the item. |