# List

**Maturity:** experimental

An inset grouped list for navigation, settings, and single selection.

## Import

```tsx
import { List } from "@liquidify/react/list"
```

## Props

- `children`: `ReactNode` (required). Sections in display order. children role: `items`.
- `className`: `string | undefined`. Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.
- `defaultValue`: `string | null | undefined`. Initial uncontrolled selection, read only on mount.
- `id`: `string | undefined`. 
- `onChange`: `((value: string) => void) | undefined`. Called once when an enabled option changes the selection.
- `ref`: `Ref<HTMLDivElement> | undefined`. Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.
- `selectionMode`: `"none" | "single" | undefined`. Group navigation, action, or static rows without selection state. Enable native radio selection across all sections.
- `value`: `string | null | undefined`. Controlled selection. `null` means nothing is selected.

## SwiftUI mapping

- `List` → `List` (direct): Inset grouped presentation
- `Section` → `List.Section` (direct): Liquidify compound API
- `List(selection:)` → `selectionMode="single", value, defaultValue, onChange` (direct): Native radio selection on the web
- `NavigationLink` → `List.Item href or onPress with disclosure` (renamed): Web convention; the host owns routing
- `LabeledContent` → `List.Item label and detail` (direct): Label/value layout within a row