# ListItem

> Slug: `list-item` · Category: Display

## When to use
- You need a single, fully-customizable content row inside a `List` or a custom layout.
- You want full control over leading decoration, body lines, status label, and trailing slot.
- You need a row that isn't covered by the specialized variants (`ListItemFilter`, `ListItemNavigation`, `ListItemTrailingIcon`, `ListItemHsi`).

## When NOT to use
- The row should toggle a checkbox or radio -> `ListItemFilter`.
- The row should navigate to another page with a chevron -> `ListItemNavigation`.
- The row needs a tappable trailing icon (info, settings, etc.) -> `ListItemTrailingIcon`.
- The row represents a Home Internet (HSI) device with WiFi status -> `ListItemHsi`.
- You want pre-styled list rows from a single data array -> `Lists`.

## Variants & decision tree
- Plain content row -> use as-is.
- Whole row links to a URL -> set `navigationUrl`.
- Need a leading device/app/avatar image -> set `leadingDecorationType` + `leadingImage`.
- Need a leading icon -> set `leadingDecorationType="icon"` + `leadingIcon`.

## States
- `inverse` — dark-background styling (inherits from theme).
- `focused` — force-focus visual for design review only.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`label`** | `string` | — | Primary row text. Required. |
| **`labelId`** | `string` | — | Unique ID for the label element (ARIA wiring). |
| `body` | `ListItemOptionalCopy[]` | — | Up to two optional copy lines below the label. |
| `status` | `StatusLabelProps` | — | Optional inline status label. |
| `leadingDecorationType` | `'device' \| 'app' \| 'avatar' \| 'icon'` | — | Leading visual type. |
| `leadingImage` | `string` | — | Image URL for device/app/avatar. |
| `leadingIcon` | `ReactNode` | — | SVG node when type is `'icon'`. |
| `leadingDecorationA11yLabel` | `string` | — | Accessible label for the decoration. |
| `dividerPosition` | `'top' \| 'bottom' \| 'none'` | `'bottom'` | Divider placement. |
| `trailingContent` | `ReactNode` | — | Trailing slot (button, toggle, icon). |
| `navigationUrl` | `string` | — | Wraps the row in an anchor. |
| `inverse` / `focused` / `className` | — | — | Standard. |

## Usage examples
```tsx
<ListItem
  label="Gigabit Pro"
  labelId="plan-gigabit"
  body={[{ text: 'Up to 1000 Mbps download' }, { text: '$99/month' }]}
  leadingDecorationType="icon"
  leadingIcon={<svg viewBox="0 0 24 24"><path d="…" /></svg>}
  leadingDecorationA11yLabel="WiFi icon"
  status={{ label: 'Active', type: 'positive' }}
/>
```

## Composition
- Render inside `<List>` (preferred) for proper `<ul>` semantics.
- Combine with `Tidbit` or `StatusLabel` in `trailingContent`.

## Accessibility
- `labelId` must be unique on the page — Arrow uses it to wire `aria-describedby`.
- Keep `body` to two entries max; over two breaks visual rhythm and a11y patterns.

## Do / Don't
- Do: pass real SVG nodes to `leadingIcon`.
- Do: provide `leadingDecorationA11yLabel` for non-decorative icons.
- Don't: use this for navigation rows — `ListItemNavigation` is purpose-built.
- Don't: stuff complex JSX into `label` — it's a string-only field.
