# List

- Page: https://jiguang132.com/resources/astryx/docs/list
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

A vertical collection of items with consistent spacing, dividers, and optional markers. Supports headers, icons, avatars, badges, and interactive items with click or link behavior. Use it to display ordered or unordered groups of related content.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## List

A vertical collection of items with consistent spacing, dividers, and optional markers. Supports headers, icons, avatars, badges, and interactive items with click or link behavior. Use it to display ordered or unordered groups of related content.

| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode |  | List items (ListItem components). |
| density | 'compact' \| 'balanced' \| 'spacious' | 'balanced' | Spacing density for items. |
| hasDividers | boolean | false | Show dividers between items. |
| edgeCompensation | 'inline' |  | Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged. |
| header | ReactNode |  | Header content, associated with the list via aria-labelledby. |
| listStyle | 'none' \| 'disc' \| 'decimal' \| 'circle' | 'none' | List marker style. 'decimal' renders an <ol> element instead of <ul>. |
| start | number | 1 | Starting number for ordered lists (listStyle='decimal'). Sets the CSS counter to begin at this value. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}. |

### Usage guidance

- Provide a header to label the list and give context to screen readers.
- Use start and end content slots to add icons, avatars, or badges to each item.
- Avoid: Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.
- Avoid: Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.
- Avoid: Mix clickable and non-clickable items in the same list without clear visual distinction.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-list",
      "visualProps": [
        "density",
        "listStyle"
      ]
    },
    {
      "className": "astryx-list-item"
    }
  ]
}
```

## ListItem



### Anatomy

- **List title**: Heading that labels the list.
- **Description**: Supplementary text below the title.
- **List items**: Individual entries, which may include icons or images.
- **Item description**: Additional detail for an individual list item.

## List Item

List item with label, description, start/end content slots, and interactive patterns.

| Prop | Type | Default | Description |
|---|---|---|---|
| label * | 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. |
| interactiveRef | RefObject<HTMLElement \| null> |  | Ref to a nested control (e.g. a checkbox in startContent) that owns the item's keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href; those are ignored when set. |
| href | string |  | Link URL; enables the invisible anchor pattern. The destination follows the shared navigation rule described on the Link `href` prop. |
| target | string |  | Link target attribute, only applicable when href is provided. target="_blank" automatically adds noopener noreferrer. |
| rel | string |  | Link relationship tokens. noopener noreferrer are merged automatically for target="_blank". |
| isDisabled | boolean | false | Disabled state; sets aria-disabled on the item. |
| isSelected | boolean | false | Selected state; sets aria-selected on the item. |
| swipeActions | {leading?: ItemSwipeAction[]; trailing?: ItemSwipeAction[]} |  | Swipe actions for touch, passed through to Item unchanged: the verbs a sideways drag uncovers on each side, each `{id?, label, icon?, onActivate, isDisabled?, variant?: 'neutral' \| 'accent' \| 'destructive', hasRemoval?}`. See Item.swipeActions; List clips its rows in the inline axis for them. |
| swipeBehavior | 'reveal' \| 'commit' | 'reveal' | What a swipe does, passed through to Item unchanged. See Item.swipeBehavior. |


## Examples

- List Item: List items with icons, descriptions, and end content slots demonstrating the full ListItem API.
- List: 
- List — Basic: Simple list with labels and descriptions for settings-style layouts.
- List — Bulleted Features: Bulleted list of feature highlights using disc markers.
- List Item — Basic: Basic list items with labels and descriptions. Use this structure for settings, navigation summaries, and other simple collections.
- List Item — Media: List items with leading avatars and icons. Use startContent for compact visual identifiers that help users scan the collection.
- List Item — Metadata: List items with end-aligned metadata. Use endContent for badges, counts, timestamps, and compact status details.
- List — Message List: Chat-style message list with avatars, preview text, and unread badges.
- List — Ordered Steps: Numbered step-by-step instructions using decimal list markers.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt