# ListItemFilter

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

## When to use
- A list row that selects one of many (radio) or many of many (checkbox) — e.g., filter sheets, plan pickers, settings toggles.
- You want the entire row to be the click target, not just a small input.

## When NOT to use
- Standalone form inputs outside a list — use `Checkbox` or `RadioGroup`.
- Single-row with a switch (on/off) — use `Lists` with `ListItemType.TOGGLE` or `ListItem` with a `Toggle` in `trailingContent`.
- Plain navigation rows -> `ListItemNavigation`.

## Variants & decision tree
- Multi-select filters -> `trailingContentType="checkbox"`.
- Single-select within a group -> `trailingContentType="radio"` plus a shared `radioGroupName`.

## States
- `checked` — current selection state.
- `inverse` — dark-background styling.
- `focused` — force-focus visual for design review.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`label`** | `string` | — | Primary row text. |
| **`trailingContentType`** | `'checkbox' \| 'radio'` | — | Selection mode. |
| `radioGroupName` | `string` | — | Required when type is `'radio'`. |
| `labelId` | `string` | auto | Auto-generated if omitted. |
| `body` | `OptionalCopy[]` | — | Up to two body lines. |
| `status` | `StatusLabelProps` | — | Inline status pill. |
| `leadingDecorationType` | `'device' \| 'app' \| 'avatar' \| 'icon'` | — | Leading visual type. |
| `leadingImage` / `leadingIcon` / `leadingDecorationA11yLabel` | — | — | Leading decoration data. |
| `dividerPosition` | `'top' \| 'bottom' \| 'none'` | `'bottom'` | Divider placement. |
| `checked` | `boolean` | `false` | Selection state. |
| `inverse` / `focused` / `className` | — | — | Standard. |

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

<List background="secondary">
  <ListItemFilter
    label="WiFi 6"
    trailingContentType="checkbox"
    checked={features.wifi6}
    body={[{ text: 'Faster speeds, lower latency' }]}
  />
  <ListItemFilter
    label="Mesh"
    trailingContentType="radio"
    radioGroupName="topology"
    checked={topology === 'mesh'}
  />
</List>
```

## Composition
- Place inside `<List>` for an `<ul>` container.
- Combine with `Chips` (variant `'toggle'` or `'radio'`) for compact pill-shaped filters elsewhere on the page.

## Accessibility
- The whole row is a label for the trailing input — clicks anywhere toggle the control.
- Provide a unique `labelId` (or let it auto-generate) so the input gets a stable name.
- For radio groups, every row must share the same `radioGroupName`.

## Do / Don't
- Do: use checkboxes for independent toggles, radios for one-of-many.
- Do: keep labels short and parallel.
- Don't: mix checkbox and radio rows in the same logical group.
- Don't: nest a separate `Checkbox` / `RadioGroup` inside the row — the trailing control is built in.
