# Lists

> Slug: `lists` · Category: Display

## When to use
- You have a single, mixed-type list of rows (plain, navigation, link, button-styled-as-link, toggle) defined as data.
- You want Arrow's styled list with built-in dividers, sizing, and surface options without composing each row by hand.
- Settings menus, account dashboards, FAQ-style indexes, app preferences.

## When NOT to use
- You need full row customization (custom trailing widgets, complex bodies) -> compose `List` with `ListItem` (or its specialized variants).
- The data is tabular -> `Table`.
- Each row should select one-of-many or many-of-many -> `ListItemFilter` inside `<List>` (or use `RadioGroup` / `Checkbox` for non-list contexts).

## Variants & decision tree
- Item types come from the `ListItemType` enum: `PLAIN`, `NAV`, `LINK`, `BUTTON_STYLED_AS_LINK` (`button`), `TOGGLE`.
- Sizing: `ListSize.SMALL` for dense menus, `ListSize.LARGE` for primary navigation.
- Visual style via `ListStyle`: `DIVIDER` (horizontal rules), `CONTAIN` (boxed rows), `SPAN` (full-width), `NONE`.
- Backgrounds via `ListBackground`: `PRIMARY`, `SECONDARY`, `NONE`.

## States
- Per-item: `disabled`, `toggleChecked`, `focused`.
- Container: `inverse` (dark-background).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`listItems`** | `ListItem[]` | — | The rows. Items without `label` are filtered out. |
| `size` | `ListSize` | `SMALL` | Typography and image sizing. |
| `background` | `ListBackground` | `NONE` | Surface fill for items. |
| `listStyle` | `ListStyle` | `DIVIDER` | Visual treatment between rows. |
| `elevation` | `boolean` | `false` | Adds elevation when `listStyle = CONTAIN` and `background ≠ NONE`. |
| `inverse` | `boolean` | inherits | Dark-background styling. |

## Usage examples
```tsx
import { Lists, ListItemType, ListSize, ListStyle } from 'arrow-react-bootstrap';

<Lists
  size={ListSize.LARGE}
  listStyle={ListStyle.DIVIDER}
  listItems={[
    { label: 'Account details', type: ListItemType.NAV, href: '/account' },
    { label: 'Payment methods', type: ListItemType.LINK, linkText: 'Manage', href: '/pay' },
    { label: 'Notifications', type: ListItemType.TOGGLE, id: 'notif', toggleChecked: true },
    { label: 'Terms of service', type: ListItemType.PLAIN },
  ]}
/>
```

## Composition
- Use as the primary content of a settings page, or inside `BillCard`'s `lists` slot.
- Pair with `SectionHeader` above for a labelled group.
- For richer rows (status pills, multi-line bodies, custom trailing slots), drop down to `List` + `ListItem`.

## Accessibility
- The container is a real `<ul>`. NAV/LINK rows render anchors; TOGGLE rows render real toggles with associated labels.
- Toggle rows must have a unique `id`.
- Pass `imageA11yLabel` for non-decorative leading images.

## Do / Don't
- Do: use the enums (`ListItemType`, `ListSize`, `ListStyle`) for type safety and refactor stability.
- Do: keep label text parallel — they appear as a sibling group.
- Don't: import `ListsLink`, `ListsNav`, `ListsToggle` — they're internal to Arrow and not exported.
- Don't: mix `Lists` and `List` for one logical group — pick one source of truth.
