# List

> Slug: `list` · Category: Display

## When to use
- You need a simple semantic `<ul>` container styled with Arrow tokens to host custom rows (e.g., `ListItem`, `ListItemFilter`, `ListItemNavigation`, `ListItemTrailingIcon`, `ListItemHsi`).
- You're composing a list with mixed item types or heavily customized children that the data-driven `Lists` component does not cover.

## When NOT to use
- You need a styled list with built-in plain / nav / link / button / toggle row variants — use `Lists` (data-driven, plural).
- You need a single content row inside a card or panel — use `ListItem` directly without a wrapping `List`.
- You need a chart legend, FCC nutrition label, or table — use `Legend`, `BroadbandFacts`, or `Table`.

## Variants & decision tree
- Default surface fill -> omit `background` (or `'primary'`).
- Inset list on a tinted surface -> `background="secondary"`.
- Elevated card-like surface -> `background="elevation"`.

## States
- `inverse` — sets `data-inverse="true"` for dark backgrounds (inherited from `ArrowThemeProvider` if unset).
- No interactive states. Interaction state lives on the child rows.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | List item rows (`ListItem`, `ListItemFilter`, etc.). |
| `background` | `'primary' \| 'secondary' \| 'elevation'` | `'primary'` | Background fill style. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Additional class names. |

## Usage examples
```tsx
import { List, ListItem } from 'arrow-react-bootstrap';

<List background="secondary">
  <ListItem label="Account details" labelId="row-account" dividerPosition="bottom" />
  <ListItem label="Billing" labelId="row-billing" dividerPosition="bottom" />
  <ListItem label="Notifications" labelId="row-notif" dividerPosition="none" />
</List>
```

## Composition
- Wrap any of: `ListItem`, `ListItemFilter`, `ListItemNavigation`, `ListItemTrailingIcon`, `ListItemHsi`.
- Place inside `BillCard` via the `lists` prop, or inside a `Modal` body.
- Pair with `SectionHeader` above the list for a labelled section.

## Accessibility
- Renders a real `<ul>` — semantics are preserved for screen readers.
- Each child must contribute a unique `labelId` so ARIA references resolve.
- Use `inverse` (not custom CSS) for dark contexts so contrast tokens apply.

## Do / Don't
- Do: use `List` whenever you need to compose more than one list-item row.
- Do: keep child `dividerPosition` consistent within a single list.
- Don't: nest a `List` inside another `List`.
- Don't: render plain `<li>` children — always use the Arrow list-item components.
