` attribute except `role`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `side` | `"left" \| "right"` | `"right"` | Edge the sheet slides in from. | | `size` | `DrawerSize` | `"md"` | Sheet width: `sm` 320px, `md` 420px, `lg` 560px, capped to the viewport minus 48px. `DrawerSize` is `"sm" \| "md" \| "lg"`. | | `closeOnOutsidePress` | `boolean` | `true` | Close when the backdrop is pressed. | | `closeOnEscape` | `boolean` | `true` | Close on Escape. | | `initialFocus` | `RefObject` | | Element to focus when opened; defaults to [data-autofocus], then the first tabbable element. | | `container` | `Element \| null` | `document.body` | Portal target. `undefined` uses `document.body`; `null` renders nothing until the target exists. | | `showClose` | `boolean` | `true` | Render the standard top-right icon close button automatically. Skipped while you render your own icon `Close`. | | `closeLabel` | `string` | `"Close"` | Accessible name of the automatic close button. | | `ref` | `Ref` | | Forwarded ref to the drawer element. | Trigger, Title, Description, Close and Footer take the same props as in [Dialog](https://meridui.dev/docs/components/dialog#api-reference). ## Styling | Class | Element | |---|---| | `.mrd-drawer__backdrop` | Fixed backdrop; aligns the sheet to its side | | `.mrd-drawer` | The sheet: 320 / 420 / 560px by `data-size`, capped at `100vw - 48px`, full height | Both carry `data-side="left" | "right"` and `data-state="open"`; the sheet also carries `data-size`. Title, description, footer and close use the `.mrd-dialog__*` classes. Motion is removed under `prefers-reduced-motion`. ## Accessibility Follows the [WAI-ARIA Dialog (Modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): `role="dialog"`, `aria-modal="true"`, focus trap, scroll lock and focus return. | Keys | Action | | --- | --- | | `Space` `Enter` | On the trigger, opens the drawer. | | `Tab` | Moves focus forward, wrapping inside the drawer. | | `Shift` `Tab` | Moves focus backwards, wrapping inside the drawer. | | `Esc` | Closes the drawer and returns focus to the trigger. | ## Guidelines - **Do:** Use a drawer for secondary content that benefits from keeping the page in view: filters, details, settings. - **Don't:** Put a multi-step flow in a drawer; use a page. ## Related - [Dialog](https://meridui.dev/docs/components/dialog) - [SidebarNav](https://meridui.dev/docs/components/sidebar-nav) for persistent navigation. --- DropdownMenuBasic, DropdownMenuCheckboxes, DropdownMenuPlacement, } from "@/examples/dropdown-menu"; # DropdownMenu A list of actions or toggles opened from a button. ```tsx dropdownMenuBasicCode ``` ## Import ```tsx import { DropdownMenu } from "@meridui/react"; ``` ## Anatomy ```tsx ``` - **Root** holds the open state. It renders no element. - **Trigger** is a `} /> ``` ## Import ```tsx import { EmptyState } from "@meridui/react"; ``` ## Examples ### Plain `variant="plain"` drops the tray background — use it inside a card or table frame that already has a surface. `titleLevel` sets the heading level to fit the page outline. ```tsx } title="No results for “quarterly”" description="Try a shorter search or check the spelling." action={} titleLevel={2} /> ``` ### Title only Only `title` is required. ```tsx ``` ## API reference Renders a `div`; the ref and other div attributes are forwarded (the native `title` attribute is replaced by the `title` prop). | Prop | Type | Default | Description | | --- | --- | --- | --- | | `title` | `ReactNode` | | Short headline, e.g. "No invoices yet". | | `description` | `ReactNode` | | One or two sentences explaining what to do next. | | `icon` | `ReactNode` | | Icon shown in a soft accent tile. Decorative. | | `action` | `ReactNode` | | Primary action(s), usually a Button. | | `titleLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Heading level for title. | | `variant` | `"tray" \| "plain"` | `"tray"` | Surface: tray is a recessed panel, plain has no background. | ## Styling | Hook | Values | | --- | --- | | `.mrd-empty-state` | Root; `data-variant` = `tray` · `plain` | | `.mrd-empty-state__icon` | Accent-soft icon tile | | `.mrd-empty-state__title` | Heading | | `.mrd-empty-state__description` | Body text | | `.mrd-empty-state__action` | Action row | EmptyState has no component variables. ## Accessibility - The title is a real heading (`h3` by default); set `titleLevel` so it fits the surrounding outline. - The icon is `aria-hidden`; the title must carry the meaning on its own. - When the empty state replaces results after a search, announce the change — for example render the result count in a polite live region. ## Guidelines - **Do:** Say what is missing and how to fill it: “No invoices yet” plus a “New invoice” button. - **Don't:** Show a bare “No data” or a large illustration with no way forward. ## Related - [Table](https://meridui.dev/docs/components/table) — the most common place an empty state appears. - [Skeleton](https://meridui.dev/docs/components/skeleton) — while data is still loading, before you know it is empty. - [Button](https://meridui.dev/docs/components/button) — the action. --- # Field Wraps a single control with its label, helper text and error message, and wires them together — `htmlFor`, `aria-describedby`, `aria-invalid`, `required` and `disabled` — through context. ```tsx ``` ## Import ```tsx import { Field } from "@meridui/react"; ``` ## Examples ### Error When `error` is set, the control gets `aria-invalid="true"` and the invalid style, and the message is appended to its `aria-describedby`. Pass `undefined`, `null` or `false` to clear it. ```tsx ``` ### Controlled input Field does not own the value. Control the child as usual and derive `error` from your state. ```tsx const [name, setName] = useState(""); const error = name.length > 0 && name.length < 3 ? "Use at least 3 characters." : undefined; setName(event.target.value)} /> ``` ### Uncontrolled input With `defaultValue` and `name`, the control keeps its own state and submits with the form. ```tsx

</Field>
```

### Disabled

`disabled` disables the control and dims the label.

```tsx
<Field label="Plan" disabled>
  <NativeSelect defaultValue="team">
    <option value="free">Free</option>
    <option value="team">Team</option>
  </NativeSelect>
</Field>
```

### Which controls read Field

[Input](https://meridui.dev/docs/components/input), [Textarea](https://meridui.dev/docs/components/textarea) and [NativeSelect](https://meridui.dev/docs/components/native-select) read the full wiring. Props set on the control itself always win over the Field's.

- [Checkbox](https://meridui.dev/docs/components/checkbox) is named by the Field label. Its own children still render as a clickable label but become its description (`aria-describedby`), so it is never double-labelled.
- [Switch](https://meridui.dev/docs/components/switch) takes the Field id (so the Field label names it), `aria-describedby`, `aria-invalid` and `disabled`.
- [RadioGroup](https://meridui.dev/docs/components/radio) is named by the Field label (`aria-labelledby`) and picks up its description, error, `required` and `disabled`.

Every control follows the same convention: `aria-invalid` carries the semantics and `data-invalid` drives the styling.

## API reference

`Field` renders a `<div>`, forwards its ref and passes other div attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` |  | Visible label, wired to the control via htmlFor. |
| `children` | `ReactNode` |  | A single Merid control; it picks up the wiring from context. |
| `description` | `ReactNode` |  | Helper text below the control, linked via aria-describedby. |
| `error` | `ReactNode` |  | Error message. Sets aria-invalid on the control and links the message. |
| `required` | `boolean` | `false` | Marks the control required and shows the visual marker. |
| `disabled` | `boolean` | `false` | Disables the control and dims the label. |
| `id` | `string` |  | Explicit id for the control. Generated when omitted. |

For custom controls, `useFieldContext()` returns the wiring (`controlId`, `labelId`, `descriptionId`, `errorId`, `invalid`, `required`, `disabled`) or `null` outside a Field.

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-field` | Root |
| `.mrd-field__description` | Helper text |
| `.mrd-field__error` | Error message |
| `data-invalid` | Present when `error` is set |
| `data-disabled` | Present when `disabled` |

The label is a [Label](https://meridui.dev/docs/components/label) (`.mrd-label`).

## Accessibility

- The label names the control; the description and error are read after it through `aria-describedby`.
- The error is not a live region. When validating on submit, move focus to the first invalid control so the message is announced.
- `required` is set on the control, so it is announced and native validation applies.

## Guidelines

- **Do:** Write errors that say how to fix the problem: “Use at least 3 characters.”
- **Don't:** Show “Invalid input”, or put more than one control inside a Field.

## Related

- [Label](https://meridui.dev/docs/components/label) — the label Field renders.
- [Input](https://meridui.dev/docs/components/input), [Textarea](https://meridui.dev/docs/components/textarea), [NativeSelect](https://meridui.dev/docs/components/native-select), [Checkbox](https://meridui.dev/docs/components/checkbox), [Switch](https://meridui.dev/docs/components/switch), [RadioGroup](https://meridui.dev/docs/components/radio) — controls that read Field.

---

# FileUpload

A file picker with a drag-and-drop zone. The browse button is the keyboard and screen reader path; dropping is a shortcut for the pointer. Files are checked against `accept`, size and count before they are kept.

```tsx
<Field label="Attachments" error={error}>
  <FileUpload
    multiple
    maxFiles={3}
    maxSize={2_000_000}
    accept="image/*,.pdf"
    description="PNG, JPG or PDF, up to 2 MB each. Three files at most."
    value={files}
    onValueChange={setFiles}
    onReject={(rejections) => setError(describe(rejections))}
    name="attachments"
  />
</Field>
```

## Import

```tsx
import { FileUpload, type FileRejection } from "@meridui/react";
```

## Examples

### Single file

Without `multiple`, a new file replaces the old one.

```tsx
<Field label="Avatar">
  <FileUpload accept="image/*" label="Drop an image" buttonLabel="Choose image" onValueChange={(files) => setFile(files[0] ?? null)} />
</Field>
```

### Disabled

```tsx
<FileUpload disabled description="Uploads are paused." />
```

### Uploading

FileUpload only selects files. Send them from `onValueChange` (or on form submit — with `name`, the kept files are mirrored onto the real `<input type="file">`) and show progress with [Progress](https://meridui.dev/docs/components/progress).

## API reference

Renders a `div`; other `div` attributes and the ref go on it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue` | `File[]` |  | Controlled or initial files. |
| `onValueChange` | `(files: File[]) => void` |  | Called with every kept file after an add or remove. |
| `onReject` | `(rejections: FileRejection[]) => void` |  | Files that failed a check, with reasons: file-invalid-type, file-too-large, file-too-small, too-many-files. |
| `accept` | `string` |  | As on <input type="file">: "image/*,.pdf". Also checked on drop. |
| `multiple` | `boolean` | `false` | Keep more than one file. |
| `maxSize / minSize` | `number` |  | Size limits in bytes. |
| `maxFiles` | `number` |  | Most files kept when multiple. |
| `label` | `ReactNode` | `"Drag and drop files here"` | Main line in the dropzone. |
| `buttonLabel` | `ReactNode` | `"Browse files"` | Text of the browse button. |
| `description` | `ReactNode` |  | Hint under the label; describes the button. |
| `showFileList` | `boolean` | `true` | Render the file list with remove buttons. |
| `getRemoveLabel` | `(file: File) => string` | `Remove {name}` | Accessible name of a remove button. |
| `getStatusText` | `(count: number) => string` | `"N file(s) selected"` | Announced when the selection changes. |
| `locale` | `string` |  | Locale for file sizes (Intl units). |
| `icon` | `ReactNode` |  | Icon above the label. |
| `invalid / disabled / required` | `boolean` |  | States; inside a Field they come from it. |
| `name` | `string` |  | Name of the file input for native form submit. |

## Styling

| Class | Element |
|---|---|
| `.mrd-file-upload` | Root (`data-dragging`, `data-invalid`, `data-disabled`) |
| `.mrd-file-upload__dropzone` | Dashed drop area |
| `.mrd-file-upload__icon`, `__label`, `__description`, `__button` | Dropzone content |
| `.mrd-file-upload__list`, `__item`, `__name`, `__size`, `__remove` | File list |

## Accessibility

Drag and drop has no keyboard equivalent, so the dropzone is not focusable; the browse button inside it is. It is described by `description` and, inside a Field, named by the visible button text followed by the field label. Adding or removing files updates a visually hidden `role="status"` region ("2 files selected"). Removing a file returns focus to the browse button.

| Keys | Action |
| --- | --- |
| `Tab` | Browse button, then each remove button. |
| `Enter` `Space` | On the browse button: open the file picker. On a remove button: remove that file. |

## Related

- [Field](https://meridui.dev/docs/components/field) — label, hint and error around a control.
- [Progress](https://meridui.dev/docs/components/progress) — upload progress.

---

# Grid

A two-dimensional CSS grid for rows of cards, stats and tiles. Pick a fixed column count, or let columns auto-fit by a minimum width.

```tsx
<Grid>
  <Box>1</Box>
  <Box>2</Box>
  <Box>3</Box>
  <Box>4</Box>
  <Box>5</Box>
  <Box>6</Box>
</Grid>
```

## Import

```tsx
import { Grid } from "@meridui/react";
```

## Examples

### Fixed columns

`columns` sets 1–6 equal columns (default 3). At 640px and below, a fixed grid collapses to a single column.

```tsx
<Grid columns={4} gap={3}>
  {items.map((item) => <Box key={item.id}>{item.label}</Box>)}
</Grid>
```

### Auto-fit

`minItemWidth` switches to `auto-fit`: as many columns as fit, each at least that wide. It overrides `columns` and needs no breakpoint.

```tsx
<Grid minItemWidth={140} gap={4}>
  {items.map((item) => <Box key={item.id}>{item.label}</Box>)}
</Grid>
```

## API reference

Renders a `div` unless `as` is given; forwards its ref and passes all HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Fixed number of equal columns. Collapses to one at ≤ 640px. Ignored when minItemWidth is set. |
| `minItemWidth` | `number \| string` |  | Responsive auto-fit: each column is at least this wide (number = px). |
| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 10 \| 14 \| 16 \| 18 \| 28` | `6` | Gap from the --mrd-space-* scale (6 = 24px). |
| `as` | `ElementType` | `"div"` | Element or component to render instead of a div. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-grid` | Root element |
| `data-layout` | `fixed` (columns) · `auto` (minItemWidth) |

Component variables, set inline from props: `--mrd-grid-gap`, `--mrd-grid-columns` (fixed layout) and `--mrd-grid-min` (auto layout).

```css
@media (min-width: 1024px) {
  .dashboard.mrd-grid { --mrd-grid-columns: 4; }
}
```

## Accessibility

- Grid is layout only and adds no role — it is not an ARIA `grid`. Use `as="ul"` with `li` children for a list of items.
- Items flow in DOM order; keep that order meaningful for keyboard and screen reader users.

## Guidelines

- **Do:** Prefer `minItemWidth` for card collections so the grid adapts to any container width.
- **Don't:** Use Grid for a single row of buttons or form controls — that is a `Stack`.

## Related

- [Stack](https://meridui.dev/docs/components/stack) — one-dimensional layout.
- [Card](https://meridui.dev/docs/components/card) — the usual grid item.
- [Container](https://meridui.dev/docs/components/container) — caps the grid's width.

---

# Heading

Semantic `h1`–`h6` in Merid's heading style: weight 600, negative tracking and `text-wrap: balance`. The visual size is independent of the level, so the outline stays correct while the design stays consistent.

```tsx
<Heading level={2}>Ship calmer interfaces</Heading>
```

## Import

```tsx
import { Heading } from "@meridui/react";
```

## Examples

### Default sizes

Each level has a default size: level 1 is `display`, 2 is `h2`, 3 is `h3`, and 4–6 map to `lg`, `md` and `sm`.

```tsx
<Heading level={1}>Display</Heading>
<Heading level={2}>Heading h2</Heading>
<Heading level={3}>Heading h3</Heading>
<Heading level={4}>Heading lg</Heading>
<Heading level={5}>Heading md</Heading>
<Heading level={6}>Heading sm</Heading>
```

### Size independent of level

Pick `level` from the document outline and `size` from the design. A settings panel title may be an `h2` that looks like a small heading.

```tsx
<Heading level={2} size="lg">Billing history</Heading>
<Heading level={3} size="sm">Invoices</Heading>
```

## API reference

`Heading` forwards its ref to the heading element and passes other HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Semantic level: renders h1–h6. |
| `size` | `"display" \| "h2" \| "h3" \| "lg" \| "md" \| "sm"` |  | Visual size. Defaults by level: display, h2, h3, lg, md, sm. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-heading` | Root <h1>–<h6> |
| `data-size` | `display` · `h2` · `h3` · `lg` · `md` · `sm` |

Sizes read the typography tokens (see [Typography](https://meridui.dev/docs/foundations/typography)); there are no heading-specific variables.

## Accessibility

- Keep one `h1` per page and do not skip levels going down; change `size`, not `level`, to adjust the look.
- Never use a heading only for large text — use [Text](https://meridui.dev/docs/components/text) with `size="lg"`.

## Guidelines

- **Do:** Choose `level` from the page outline and `size` from the design.
- **Don't:** Jump from `h2` to `h5` because the smaller size looked right.

## Related

- [Text](https://meridui.dev/docs/components/text) — body copy and captions.
- [VisuallyHidden](https://meridui.dev/docs/components/visually-hidden) — headings that only assistive tech needs.

---

# HoverCard

A preview card shown after a short delay when a link is hovered or focused: a profile, a repository, a page summary.

```tsx
hoverCardBasicCode
```

## Import

```tsx
import { HoverCard } from "@meridui/react";
```

## Anatomy

```tsx
<HoverCard.Root>
  <HoverCard.Trigger />
  <HoverCard.Content />
</HoverCard.Root>
```

- **Root** holds the open state and the delays. It renders no element.
- **Trigger** is an `<a>`; with `asChild` it merges onto your own [Link](https://meridui.dev/docs/components/link) or router link.
- **Content** is the portalled card, positioned against the trigger. It only mounts while open.

## Examples

### Delays and placement

`openDelay` (default 500ms) avoids flashing cards while the pointer passes by; `closeDelay` (default 300ms) lets the pointer travel from the link onto the card, which stays open while hovered.

```tsx
hoverCardDelaysCode
```

## API reference

### Root

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the open state should change. |
| `openDelay` | `number` | `500` | Delay before opening on hover or focus, in ms. |
| `closeDelay` | `number` | `300` | Delay before closing after the pointer leaves, in ms. |

### Trigger

Accepts every `<a>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | `false` | Render the single child element (e.g. your own Link) instead of an <a>, merging props, ref and handlers. |
| `ref` | `Ref<HTMLAnchorElement>` |  | Forwarded ref. |

### Content

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `Placement` | `"bottom"` | Preferred placement relative to the trigger. |
| `sideOffset` | `number` | `8` | Distance from the trigger in px. |
| `container` | `Element \| null` | `document.body` | Portal target. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the card. |

## Styling

| Class | Element |
|---|---|
| `.mrd-hover-card` | Content |

| Attribute | On | Values |
|---|---|---|
| `data-state` | Trigger | `open`, `closed` |
| `data-state` | Content | `open` |

## Accessibility

A hover card is supplementary: it opens on hover and on keyboard focus, but screen readers are not told about it and its content is not in the Tab order. The trigger must make sense on its own (the link goes to the full profile), and nothing essential or interactive should live only in the card. Touch hover is ignored. For interactive content, use a [Popover](https://meridui.dev/docs/components/popover).

| Keys | Action |
| --- | --- |
| `Tab` | Focusing the trigger opens the card after openDelay; leaving closes it. |
| `Escape` | Close the card. |

## Guidelines

- **Do:** Preview something the link points to: who a person is, what a repository contains.
- **Don't:** Put buttons, forms or the only copy of information in a hover card.

## Related

- [Tooltip](https://meridui.dev/docs/components/tooltip): a short text label for a control.
- [Popover](https://meridui.dev/docs/components/popover): a click-opened panel that can hold interactive content.

---

# IconButton

A square, icon-only button for toolbars, dismiss actions and dense rows. Because there is no visible text, `label` is required and becomes the `aria-label`.

```tsx
<IconButton label="Settings" icon={<SettingsIcon />} />
```

## Import

```tsx
import { IconButton } from "@meridui/react";
```

## Examples

### Variants

`ghost` (the default) is transparent until hovered — right for toolbars and card corners. `secondary` gives the button a visible surface; `primary` uses the accent fill and should be as rare as a primary [Button](https://meridui.dev/docs/components/button).

```tsx
<IconButton variant="ghost" label="Settings" icon={<SettingsIcon />} />
<IconButton variant="secondary" label="Delete" icon={<TrashIcon />} />
<IconButton variant="primary" label="Add item" icon={<PlusIcon />} />
```

### Sizes

Squares of 32px (`sm`), 36px (`md`, default) and 40px (`lg`).

```tsx
<IconButton size="sm" label="Close" icon={<CloseIcon />} />
<IconButton size="md" label="Close" icon={<CloseIcon />} />
<IconButton size="lg" label="Close" icon={<CloseIcon />} />
```

### Disabled

```tsx
<IconButton variant="secondary" label="Delete" icon={<TrashIcon />} disabled />
```

## API reference

Forwards its ref to the `<button>` and passes native button attributes through, except `children` and `aria-label` (use `label`). `type` defaults to `"button"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` |  | Accessible name, rendered as aria-label. |
| `icon` | `ReactNode` |  | The icon. Rendered inside an aria-hidden span. |
| `variant` | `"ghost" \| "secondary" \| "primary"` | `"ghost"` | Visual style. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Square size: sm 32px, md 36px, lg 40px. |
| `type` | `"button" \| "submit" \| "reset"` | `"button"` | Native button type. |
| `disabled` | `boolean` |  | Native disabled attribute. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-icon-button` | Root `<button>` |
| `.mrd-icon-button__icon` | Icon wrapper (aria-hidden) |
| `data-variant` | `ghost` · `secondary` · `primary` |
| `data-size` | `sm` · `md` · `lg` |

Component variable: `--mrd-icon-button-size`, set per size from the `--mrd-icon-button-sm/md/lg` tokens.

```css
.toolbar .mrd-icon-button {
  --mrd-icon-button-size: 28px;
}
```

## Accessibility

- `label` is required by the types and becomes `aria-label`; the icon is `aria-hidden`.
- Write the label as the action (“Delete invoice”), not the icon's shape (“Trash can”).
- Pair with [Tooltip](https://meridui.dev/docs/components/tooltip) so sighted mouse users can discover the label too.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the button. |
| `Enter` | Activates the button. |
| `Space` | Activates the button. |

## Guidelines

- **Do:** Use icon buttons for well-known actions — close, settings, more — where the icon is unambiguous.
- **Don't:** Use an icon button for a primary or unfamiliar action. If people must guess, use a `Button` with a label.

## Related

- [Button](https://meridui.dev/docs/components/button) — actions with a visible label.
- [Tooltip](https://meridui.dev/docs/components/tooltip) — shows the label on hover and focus.

---

# Input

A single-line text input. Inside a [Field](https://meridui.dev/docs/components/field) it picks up its id, description, error and required state automatically.

```tsx
<Input aria-label="Email" type="email" placeholder="you@company.com" />
```

## Import

```tsx
import { Input } from "@meridui/react";
```

## Examples

### Sizes

`sm` 36px, `md` 46px (default), `lg` 50px.

```tsx
<Input size="sm" placeholder="Small, 36px" />
<Input size="md" placeholder="Medium, 46px" />
<Input size="lg" placeholder="Large, 50px" />
```

### Leading and trailing

`leading` and `trailing` add decorative icons, prefixes or units inside the frame. They are `aria-hidden`, so put anything meaningful (like a currency) in the label too. When either is set, the input is wrapped in `.mrd-input-group` and `className` moves to the wrapper.

```tsx
<Input aria-label="Search" leading={<SearchIcon />} placeholder="Search projects" />
<Input aria-label="Amount" type="number" trailing="TRY" defaultValue="250" />
```

### Invalid, disabled, read-only

`invalid` forces the invalid style and `aria-invalid`; inside a Field it follows the Field's `error`. `disabled` and `readOnly` are the native attributes.

```tsx
<Input aria-label="Invalid" invalid defaultValue="not-an-email" />
<Input aria-label="Disabled" disabled defaultValue="Disabled" />
<Input aria-label="Read only" readOnly defaultValue="Read only" />
```

### Controlled

Input is a plain `<input>`: use `value` + `onChange` to control it, or `defaultValue` to leave it uncontrolled.

```tsx
const [value, setValue] = useState("");

<Input
  aria-label="Workspace URL"
  value={value}
  onChange={(event) => setValue(event.target.value)}
  placeholder="acme"
/>
<Text size="xs" tone="muted">meridui.dev/{value || "…"}</Text>
```

## API reference

`Input` forwards its ref to the `<input>` and passes every other native input attribute through. `className` and `style` always go on the root element: the `<input>` itself, or the `.mrd-input-group` wrapper when `leading` or `trailing` is set. `type` defaults to `"text"`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height: sm 36px, md 46px, lg 50px. |
| `invalid` | `boolean` |  | Forces the invalid style (`data-invalid`) and `aria-invalid`. Inside a Field, derived from its error. |
| `leading` | `ReactNode` |  | Decorative element before the text (icon, prefix). |
| `trailing` | `ReactNode` |  | Decorative element after the text (icon, unit). |
| `type` | `string` | `"text"` | Native input type. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-input` | The <input> |
| `.mrd-input-group` | Wrapper, only when `leading` or `trailing` is set |
| `.mrd-input-group__addon` | Addon slot, with `data-side` `leading` · `trailing` |
| `data-size` | `sm` · `md` · `lg` (on input and group) |
| `data-invalid` | Present when invalid; drives the danger border (`aria-invalid` carries the semantics) |

Component variable: `--mrd-input-height`, set per size.

```css
.filters .mrd-input {
  --mrd-input-height: 40px;
}
```

## Accessibility

- Every input needs a name: a visible [Label](https://meridui.dev/docs/components/label) / [Field](https://meridui.dev/docs/components/field), or `aria-label` when the purpose is obvious from context (like search).
- Placeholder text is not a label; it disappears when typing and has low contrast.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the input. |

## Guidelines

- **Do:** Match the input `size` to neighbouring buttons so a row shares one height.
- **Don't:** Put interactive elements like buttons in `leading` or `trailing` — addons are hidden from assistive tech.

## Related

- [Field](https://meridui.dev/docs/components/field) — label, description and error wiring.
- [Textarea](https://meridui.dev/docs/components/textarea) — multi-line text.
- [NativeSelect](https://meridui.dev/docs/components/native-select) — pick from a list.

---

# Kbd

A key cap for showing keyboard shortcuts in text, menus and tooltips. Renders a semantic `<kbd>`.

```tsx
<Text>
  Press <Kbd>Ctrl</Kbd> <Kbd>K</Kbd> to search.
</Text>
```

## Import

```tsx
import { Kbd } from "@meridui/react";
```

## Examples

### Sizes

`md` (default) sits in body text; `sm` fits inside menu items, tooltips and dense rows.

```tsx
<Kbd size="sm">Esc</Kbd>
<Kbd size="md">Esc</Kbd>
```

### Chords

Render one `Kbd` per key and put the separator between them as plain text.

```tsx
<Kbd>Ctrl</Kbd> + <Kbd>Shift</Kbd> + <Kbd>P</Kbd>
```

## API reference

`Kbd` forwards its ref to the `<kbd>` and passes other HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md"` | `"md"` | Size of the key cap. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-kbd` | Root <kbd> |
| `data-size` | `sm` · `md` |

## Accessibility

- `<kbd>` is read as its text. Spell out symbols that screen readers pronounce poorly — prefer “Ctrl” over “⌃”, or add a [VisuallyHidden](https://meridui.dev/docs/components/visually-hidden) name next to the glyph.
- Kbd is not interactive; it documents a shortcut, it does not bind one.

## Guidelines

- **Do:** Use one cap per key, with the key names your users see on their keyboard.
- **Don't:** Put a whole shortcut like “Ctrl+Shift+P” inside a single cap.

## Related

- [Code](https://meridui.dev/docs/components/code) — inline code and commands.
- [Text](https://meridui.dev/docs/components/text) — the running text Kbd usually sits in.

---

# Label

A form label: 14px, weight 500, ink. Use it directly when you wire a control yourself; [Field](https://meridui.dev/docs/components/field) renders one for you.

```tsx
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" placeholder="you@company.com" />
```

## Import

```tsx
import { Label } from "@meridui/react";
```

## Examples

### Required

`required` appends an `*` that is hidden from assistive tech. It is only a visual cue — set `required` on the control too so it is announced and validated.

```tsx
<Label htmlFor="name" required>Full name</Label>
<Input id="name" required />
```

### Disabled

`disabled` dims the label to match a disabled control. It does not disable anything by itself.

```tsx
<Label htmlFor="workspace" disabled>Workspace</Label>
<Input id="workspace" defaultValue="acme" disabled />
```

## API reference

`Label` forwards its ref to the `<label>` and passes other label attributes (`htmlFor`, `id`, …) through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `required` | `boolean` | `false` | Appends a visual * marker, hidden from assistive tech. |
| `disabled` | `boolean` | `false` | Dims the label to match a disabled control. |
| `htmlFor` | `string` |  | id of the control the label names. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-label` | Root <label> |
| `.mrd-label__required` | The required marker |
| `data-disabled` | Present when `disabled` |

## Accessibility

- Always connect the label with `htmlFor` matching the control's `id`; clicking the label then focuses the control and it becomes its accessible name.
- The `*` is `aria-hidden`; “required” is announced from the control's own `required` attribute.

## Guidelines

- **Do:** Keep labels short nouns — “Email”, “Company name” — and always visible.
- **Don't:** Rely on the placeholder as the only label.

## Related

- [Field](https://meridui.dev/docs/components/field) — label, control, description and error wired together.
- [Input](https://meridui.dev/docs/components/input), [Textarea](https://meridui.dev/docs/components/textarea), [NativeSelect](https://meridui.dev/docs/components/native-select).

---

# Link

A styled `<a>` for navigation — inline in text or standalone in lists and footers. Use a [Button](https://meridui.dev/docs/components/button) when the result is an action rather than a new location.

```tsx
<Text>
  Read the <Link href="/docs/installation">installation guide</Link> before you start.
</Text>
```

## Import

```tsx
import { Link } from "@meridui/react";
```

## Examples

### Tones

`accent` (default) is for links inside running text. `ink` and `muted` are quieter, for navigation lists and footers where every item is a link.

```tsx
<Link href="#" tone="accent">Accent</Link>
<Link href="#" tone="ink">Ink</Link>
<Link href="#" tone="muted">Muted</Link>
```

### Underline

`hover` (default) shows the underline on hover and focus. Use `always` when the link must be distinguishable without colour — for example inside a paragraph of muted text.

```tsx
<Link href="#" underline="hover">Underline on hover</Link>
<Link href="#" underline="always">Always underlined</Link>
<Link href="#" underline="none">No underline</Link>
```

### External

`external` opens the link in a new tab, sets `rel="noopener noreferrer"`, and appends a visually hidden “(opens in a new tab)” so screen reader users are warned.

```tsx
<Link href="https://github.com/ahmetcantryk/merid" external>
  GitHub repository
</Link>
```

### With a client-side router

Pass `asChild` and your router's link as the only child: it gets Merid's link styling and keeps its own behaviour. This also works from server components.

```tsx
import NextLink from "next/link";

<Link asChild tone="accent">
  <NextLink href="/pricing">Pricing</NextLink>
</Link>
```

## API reference

Forwards its ref to the `<a>` and passes all native anchor attributes through. When `external` is set, it overrides `target` and `rel`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"accent" \| "ink" \| "muted"` | `"accent"` | Text colour. |
| `underline` | `"hover" \| "always" \| "none"` | `"hover"` | When the underline shows. |
| `external` | `boolean` | `false` | Opens in a new tab with rel="noopener noreferrer" and appends a visually hidden hint. |
| `externalLabel` | `string` | `"(opens in a new tab)"` | Visually hidden hint appended to `external` links. Translate it for other languages. |
| `href` | `string` |  | Native link target. |
| `asChild` | `boolean` | `false` | Render the single child element (e.g. a router link) with link styling instead of an `<a>`. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-link` | Root `<a>` |
| `data-tone` | `accent` · `ink` · `muted` |
| `data-underline` | `hover` · `always` · `none` |

Link has no component variables; it reads `--mrd-accent`, `--mrd-accent-hover`, `--mrd-ink` and `--mrd-muted`.

## Accessibility

- Renders a native `<a>`: Enter follows it, and it appears in the screen reader's links list.
- Link text must make sense out of context — “Read the pricing guide”, not “click here”.
- `external` adds the new-tab warning; do not open new tabs silently with `target="_blank"` alone.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the link. |
| `Enter` | Follows the link. |

## Guidelines

- **Do:** Use `Link` when something takes the user somewhere; use `Button` when it does something.
- **Don't:** Attach an `onClick` to a link with `href="#"` to trigger an action.

- **Do:** Underline links that sit in muted or dense text so they are not identified by colour alone.
- **Don't:** Use `underline="none"` for links in running text.

## Related

- [Button](https://meridui.dev/docs/components/button) — the `link` variant looks like a link but performs an action.
- [VisuallyHidden](https://meridui.dev/docs/components/visually-hidden) — the utility behind the external-link hint.

---

NativeSelectDemo,
  NativeSelectSizes,
  NativeSelectField,
  NativeSelectStates,
  NativeSelectControlled,
} from "@/examples/native-select";

# NativeSelect

The platform `<select>` with Merid styling. You get the full native keyboard, the operating system's picker on mobile and form participation without any JavaScript.

```tsx
<NativeSelect aria-label="Country" placeholder="Choose a country">
  <option value="tr">Türkiye</option>
  <option value="de">Germany</option>
  <option value="nl">Netherlands</option>
</NativeSelect>
```

## Import

```tsx
import { NativeSelect } from "@meridui/react";
```

## Examples

### Sizes

`sm` is 36px, `md` 46px (default) and `lg` 50px — the same heights as [Input](https://meridui.dev/docs/components/input), so they line up in a row.

```tsx
<NativeSelect aria-label="Small" size="sm" defaultValue="a">…</NativeSelect>
<NativeSelect aria-label="Medium" size="md" defaultValue="a">…</NativeSelect>
<NativeSelect aria-label="Large" size="lg" defaultValue="a">…</NativeSelect>
```

### In a Field

Inside a [Field](https://meridui.dev/docs/components/field) the select picks up its `id`, `aria-describedby`, `required` and `disabled` from context — no manual wiring.

```tsx
<Field label="Plan" description="You can change plans at any time." required>
  <NativeSelect placeholder="Select a plan">
    <option value="free">Free</option>
    <option value="team">Team</option>
    <option value="business">Business</option>
  </NativeSelect>
</Field>
```

### Invalid and disabled

A Field `error` sets `aria-invalid` on the select and links the message. Outside a Field pass `invalid` directly.

```tsx
<Field label="Region" error="Pick a region to continue.">
  <NativeSelect placeholder="Select a region">…</NativeSelect>
</Field>

<Field label="Currency" disabled>
  <NativeSelect defaultValue="eur">
    <option value="eur">EUR</option>
  </NativeSelect>
</Field>
```

### Controlled

Use `value` and `onChange` exactly as with a native select.

```tsx
const [value, setValue] = useState("weekly");

<Field label="Digest frequency">
  <NativeSelect value={value} onChange={(e) => setValue(e.target.value)}>
    <option value="daily">Daily</option>
    <option value="weekly">Weekly</option>
    <option value="monthly">Monthly</option>
  </NativeSelect>
</Field>
```

## API reference

The ref and all native select attributes go to the `<select>`, except `className` and `style`, which are applied to the outer wrapper. The native `size` attribute is replaced by the `size` prop below.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height: sm 36px, md 46px, lg 50px. |
| `invalid` | `boolean` |  | Forces the invalid style (`data-invalid`) and `aria-invalid`. Inside a Field, derived from its error. |
| `placeholder` | `string` |  | Adds a disabled, hidden `value=""` first option, shown whenever the value is `""` (uncontrolled start or a controlled `value=""`). |
| `children` | `ReactNode` |  | option and optgroup elements. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-native-select` | Wrapper ; receives `className` and `style` |
| `.mrd-native-select__control` | The <select> |
| `.mrd-native-select__chevron` | Decorative chevron icon |
| `data-size` | `sm` · `md` · `lg` (on the wrapper) |
| `data-invalid` | On the control when invalid; drives the danger border (`aria-invalid` carries the semantics) |

Component variable: `--mrd-input-height`, shared with Input.

## Accessibility

- It is a real `<select>`, so screen readers announce it as a combobox or list box with its options, and mobile browsers open the native picker.
- Give it a name: a surrounding Field, a `Label` with `htmlFor`, or `aria-label`. The `placeholder` option is not a label.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the select. |
| `Space` | Opens the option list (platform dependent). |
| `↑` `↓` | Changes the selected option. |
| `A–Z` | Jumps to the first option starting with the typed character. |

## Guidelines

- **Do:** Use NativeSelect for plain lists of known options, especially in forms used on phones.
- **Don't:** Put rich content, icons or search inside it — reach for [Select](https://meridui.dev/docs/components/select) instead.

- **Do:** Use a `placeholder` that prompts a choice, like “Select a plan”, when there is no sensible default.
- **Don't:** Rely on the placeholder as the only label.

## Related

- [Select](https://meridui.dev/docs/components/select) — custom listbox with richer options.
- [Field](https://meridui.dev/docs/components/field) — label, description and error wiring.
- [Input](https://meridui.dev/docs/components/input) — single-line text with the same sizes.
- [SegmentedControl](https://meridui.dev/docs/components/segmented-control) — for two to five visible options.

---

# NavigationMenu

A site's top navigation: links and buttons that reveal panels of links, from a short list to a full-width mega menu.

```tsx
navigationMenuBasicCode
```

## Import

```tsx
import { NavigationMenu } from "@meridui/react";
```

## Anatomy

```tsx
<NavigationMenu.Root>
  <NavigationMenu.List>
    <NavigationMenu.Item value="products">
      <NavigationMenu.Trigger />
      <NavigationMenu.Content>
        <NavigationMenu.Link />
      </NavigationMenu.Content>
    </NavigationMenu.Item>
    <NavigationMenu.Item>
      <NavigationMenu.Link />
    </NavigationMenu.Item>
  </NavigationMenu.List>
</NavigationMenu.Root>
```

- **Root** is the `<nav>` landmark and holds which panel is open (one at a time).
- **List** and **Item** are the `<ul>` and `<li>` of the bar.
- **Trigger** is a disclosure `<button>`; **Content** is its panel of links. `fullWidth` spans the bar for a mega menu.
- **Link** is an `<a>`, directly in an Item (a top-level link) or inside Content. `description` adds a second line.

## Examples

### Router links

`asChild` renders your router's link with the same styling and behaviour; `active` sets `aria-current="page"`.

```tsx
import NextLink from "next/link";

<NavigationMenu.Link asChild active={pathname === "/pricing"}>
  <NextLink href="/pricing">Pricing</NextLink>
</NavigationMenu.Link>
```

### Mega menu

Pass `fullWidth` to Content: the panel spans the whole bar and lays links out in a responsive grid. Below 640px every panel spans the bar.

## API reference

### Root

Accepts every `<nav>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Controlled open item ("" when none). |
| `defaultValue` | `string` | `""` | Initially open item when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called with the open item value. |
| `openDelay` | `number` | `150` | Hover delay before a panel opens, in ms. Clicks and keys open at once. |
| `closeDelay` | `number` | `250` | Delay before a panel closes after the pointer leaves, in ms. |
| `aria-label` | `string` | `"Main"` | Accessible name of the navigation landmark. |
| `ref` | `Ref<HTMLElement>` |  | Forwarded ref to the <nav>. |

### Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Unique value; needed for controlled use. Defaults to a generated id. |

### Trigger, Content

Trigger accepts every `<button>` attribute; Content every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Content fullWidth` | `boolean` | `false` | Span the full width of the bar (a mega menu). |

### Link

Accepts every `<a>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Marks the current page (aria-current="page"). |
| `description` | `string` |  | Second line under the label, for links inside a panel. |
| `asChild` | `boolean` | `false` | Render the single child element (a router link) instead of an <a>. |
| `ref` | `Ref<HTMLAnchorElement>` |  | Forwarded ref. |

## Styling

| Class | Element |
|---|---|
| `.mrd-navmenu` | Root |
| `.mrd-navmenu__list`, `.mrd-navmenu__item` | List and Item |
| `.mrd-navmenu__trigger`, `.mrd-navmenu__chevron` | Trigger and its icon |
| `.mrd-navmenu__content` | Content |
| `.mrd-navmenu__link`, `.mrd-navmenu__link-title`, `.mrd-navmenu__link-description` | Link parts |

| Attribute | On | Values |
|---|---|---|
| `data-state` | Root, Item, Trigger, Content | `open`, `closed` |
| `data-full` | Content | present with `fullWidth` |
| `data-active` | Link | present when `active` |

## Accessibility

Follows the WAI-ARIA [Disclosure navigation menu](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) example rather than `role="menubar"`: site navigation is a list of links, and every trigger and link stays in the Tab order. Panels stay in the DOM while closed (`hidden`), so their links are crawlable. Focus leaving the nav, Escape or an outside press close the open panel.

| Keys | Action |
| --- | --- |
| `Enter` `Space` | On a trigger: open or close its panel. |
| `ArrowDown` | On a trigger: open and focus the first link. In a panel: next link. |
| `ArrowUp` | In a panel: previous link. |
| `ArrowRight` `ArrowLeft` | Next / previous trigger or top-level link (mirrored in RTL). |
| `Home` `End` | First / last trigger or top-level link. |
| `Escape` | Close the panel and return focus to its trigger. |
| `Tab` | Move through triggers and links in order. |

## Guidelines

- **Do:** Keep top-level labels short and put the most-visited destinations first.
- **Don't:** Use NavigationMenu for app commands. Actions belong in a [DropdownMenu](https://meridui.dev/docs/components/dropdown-menu) or [Toolbar](https://meridui.dev/docs/components/toolbar).

## Related

- [SidebarNav](https://meridui.dev/docs/components/sidebar-nav): vertical navigation for app sidebars.
- [Breadcrumb](https://meridui.dev/docs/components/breadcrumb): where the current page sits.

---

# NumberInput

A numeric field with increment and decrement buttons. Values are formatted with `Intl.NumberFormat` and typed text is parsed in the same locale, so `1.234,5` works in `tr-TR` and `1,234.5` in `en-US`.

```tsx
const [seats, setSeats] = useState<number | null>(1);

<Field label="Seats">
  <NumberInput value={seats} onValueChange={setSeats} min={1} max={50} name="seats" />
</Field>
```

## Import

```tsx
import { NumberInput } from "@meridui/react";
```

## Examples

### Currency, percent and units

`formatOptions` is passed to `Intl.NumberFormat`. For percent, the value is the fraction (`0.15` shows as `15%`).

```tsx
<NumberInput defaultValue={1499.9} step={0.5} locale="en-US" formatOptions={{ style: "currency", currency: "USD" }} />
<NumberInput defaultValue={0.15} step={0.01} min={0} max={1} formatOptions={{ style: "percent" }} />
<NumberInput defaultValue={2.5} step={0.1} locale="de-DE" formatOptions={{ style: "unit", unit: "kilogram" }} />
```

### Sizes and states

```tsx
<NumberInput aria-label="Small" size="sm" defaultValue={3} />
<NumberInput aria-label="No stepper" hideStepper defaultValue={10} />
<NumberInput aria-label="Invalid" invalid defaultValue={-1} />
<NumberInput aria-label="Disabled" disabled defaultValue={5} />
```

## API reference

Accepts every `<input>` attribute except `type`, `value`, `defaultValue`, `onChange`, `size`, `min`, `max` and `step`; the ref goes to the `<input>`. `className` and `style` go on the wrapper. Picks up [Field](https://meridui.dev/docs/components/field) wiring like [Input](https://meridui.dev/docs/components/input).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` |  | Controlled value; null is empty. |
| `defaultValue` | `number \| null` | `null` | Initial value when uncontrolled. |
| `onValueChange` | `(value: number \| null) => void` |  | Called with the committed value (on step, Enter or blur). |
| `min / max` | `number` |  | Limits. Values are clamped; the matching button disables at a limit. |
| `step` | `number` | `1` | Amount added by buttons and arrow keys. |
| `largeStep` | `number` | `step * 10` | Amount added by Page Up / Page Down. |
| `locale` | `string` | `runtime locale` | Locale for formatting and parsing. |
| `formatOptions` | `Intl.NumberFormatOptions` |  | Currency, percent, unit, fraction digits… |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height. |
| `invalid` | `boolean` |  | aria-invalid and the danger border. |
| `hideStepper` | `boolean` | `false` | Hide the buttons. |
| `incrementLabel` | `string` | `"Increase"` | Accessible name of the + button. |
| `decrementLabel` | `string` | `"Decrease"` | Accessible name of the − button. |
| `name` | `string` |  | Hidden input with the raw number (no formatting). |

## Styling

| Class | Element |
|---|---|
| `.mrd-number-input` | Wrapper (`data-size`, `data-invalid`, `data-disabled`) |
| `.mrd-number-input__field` | The `<input role="spinbutton">` |
| `.mrd-number-input__stepper`, `.mrd-number-input__step` | Button group and each button |

## Accessibility

The field is a `role="spinbutton"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and a formatted `aria-valuetext`. The buttons are not tab stops (`tabindex="-1"`): the keyboard path is the arrow keys, following the [APG spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/). Each button is at least 24×24px.

| Keys | Action |
| --- | --- |
| `ArrowUp` `ArrowDown` | Increase / decrease by step. |
| `PageUp` `PageDown` | Increase / decrease by largeStep. |
| `Home` `End` | Set to min / max (when set). |
| `Enter` | Commit the typed text. |

## Related

- [Slider](https://meridui.dev/docs/components/slider) — when an approximate value is enough.
- [Input](https://meridui.dev/docs/components/input) — for free text.

---

PaginationBasic,
  PaginationControlled,
  PaginationSiblings,
  PaginationLinks,
} from "@/examples/pagination";

# Pagination

Moves between pages of results, with previous and next controls and a compact page range.

```tsx
paginationBasicCode
```

## Import

```tsx
import { Pagination, getPageRange } from "@meridui/react";
```

## Anatomy

`Pagination` is a single component. It renders:

- a `<nav>` landmark with a list inside,
- a previous control and a next control (icon buttons with labels),
- page buttons — the first, the last, `siblingCount` pages each side of the current one,
- an ellipsis wherever two or more pages are skipped.

## Examples

### Controlled

Pass `page` and `onPageChange` when the page lives in your state or the URL.

```tsx
paginationControlledCode
```

### More siblings

`siblingCount` sets how many pages show on each side of the current one.

```tsx
paginationSiblingsCode
```

### As links

With `getHref`, each other page renders as an `<a>` so results are crawlable and open in a new tab. The current page renders as plain text (not a link to itself) with `aria-current="page"`. Disabled previous/next controls stay buttons.

```tsx
paginationLinksCode
```

For client-side routing, add `renderLink`. It receives every prop of the link (`href`, `className`, `aria-label`, `aria-current`, `onClick`, `children`, …) plus the target `page`:

```tsx
import NextLink from "next/link";

<Pagination
  pageCount={12}
  page={page}
  getHref={(p) => `/invoices?page=${p}`}
  renderLink={({ page, ...props }) => <NextLink {...props} />}
/>
```

### Custom layouts with getPageRange

`getPageRange(page, pageCount, siblings = 1)` returns the same range the component uses, as an array of page numbers and `"ellipsis-start"` / `"ellipsis-end"` markers.

```tsx
getPageRange(5, 12); // [1, "ellipsis-start", 4, 5, 6, "ellipsis-end", 12]
```

## API reference

### Pagination

Renders `<nav>` and accepts its HTML attributes except `onChange`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pageCount` | `number` |  | Total number of pages (≥ 1). |
| `page` | `number` |  | Controlled current page, 1-based. |
| `defaultPage` | `number` | `1` | Initial page when uncontrolled. |
| `onPageChange` | `(page: number) => void` |  | Called with the requested page. |
| `siblingCount` | `number` | `1` | Pages shown on each side of the current one. |
| `getHref` | `(page: number) => string` |  | When given, pages render as links with this href; the current page renders as text. |
| `renderLink` | `(props: PaginationLinkProps) => ReactNode` |  | With getHref, renders each link yourself (e.g. a router link). Spread every prop except `page` onto an element that renders an `<a>`. |
| `aria-label` | `string` | `"Pagination"` | Accessible name of the landmark. |
| `previousLabel` | `string` | `"Previous page"` | Label of the previous button. |
| `nextLabel` | `string` | `"Next page"` | Label of the next button. |
| `pageLabel` | `(page: number) => string` | `(p) => `Page ${p}`` | Builds the accessible label for a page button. |
| `ref` | `Ref<HTMLElement>` |  | Forwarded ref to the nav element. |

### getPageRange

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | `number` |  | Current page, clamped to 1…pageCount. |
| `pageCount` | `number` |  | Total pages. |
| `siblings` | `number` | `1` | Pages on each side of the current one. |

Returns `PageRangeItem[]`, where `PageRangeItem = number | "ellipsis-start" | "ellipsis-end"`.

## Styling

- `.mrd-pagination` / `.mrd-pagination__list` — nav root and the flex list.
- `.mrd-pagination__page` — a page button, link, or (current page in link mode) text: `--mrd-icon-button-md` square, `--mrd-radius-md`.
- `.mrd-pagination__page[aria-current="page"]` (also `data-state="active"`) — current page: `--mrd-accent-soft` fill, `--mrd-accent-strong` text.
- `.mrd-pagination__control` with `data-direction="previous"` or `"next"` — chevron controls; `:disabled` uses `--mrd-placeholder`.
- `.mrd-pagination__ellipsis` — the `…` gap, hidden from assistive tech.

On coarse pointers controls grow to `--mrd-icon-button-lg`. Reduced motion removes the press scale.

## Accessibility

There is no dedicated APG pattern for pagination; it follows the [landmark regions guidance](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/) for a named `navigation` region.

- The list sits inside a `nav` named "Pagination". Name it more specifically (for example "Search results pages") when a page has several.
- Every page control has an accessible label from `pageLabel`; the current page has `aria-current="page"`.
- Previous and next are disabled, not hidden, at the ends, so the layout does not shift.
- Ellipses are `aria-hidden`.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the next control. |
| `Enter` | Activates the focused page or control. |
| `Space` | Activates the focused button (button mode). |

## Guidelines

- **Do:** Show a result count near the pagination and scroll the list back to the top when the page changes.
- **Don't:** Use pagination for a handful of items or for steps in a flow. Use a Stepper for sequential tasks.

- **Do:** Use getHref when pages are real URLs, so people can share and bookmark them.
- **Don't:** Change the page size silently between pages.

## Related

- [Table](https://meridui.dev/docs/components/table)
- [Stepper](https://meridui.dev/docs/components/stepper)
- [Breadcrumb](https://meridui.dev/docs/components/breadcrumb)

---

# PinInput

One-time code and PIN entry with one cell per character. Typing moves forward, Backspace moves back, and pasting or SMS autofill fills every cell.

```tsx
<Field label="Verification code" description="We sent a 6-digit code to your phone.">
  <PinInput value={code} onValueChange={setCode} onComplete={verify} name="otp" />
</Field>
```

## Import

```tsx
import { PinInput } from "@meridui/react";
```

## Examples

### Length, mask and characters

```tsx
<PinInput aria-label="PIN" length={4} mask size="lg" />
<PinInput aria-label="Invite code" length={5} type="alphanumeric" placeholder="·" />
<PinInput aria-label="Invalid code" length={4} defaultValue="1234" invalid />
```

## API reference

Renders a `div role="group"`; name it with `aria-label`, `aria-labelledby` or a [Field](https://meridui.dev/docs/components/field). The ref goes to the group.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | `6` | Number of cells. |
| `value` | `string` |  | Controlled code. |
| `defaultValue` | `string` | `""` | Initial code when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called on every change. |
| `onComplete` | `(value: string) => void` |  | Called once every cell is filled. |
| `type` | `"numeric" \| "alphanumeric"` | `"numeric"` | Accepted characters; numeric opens the number pad on mobile. |
| `mask` | `boolean` | `false` | Hide characters like a password. |
| `placeholder` | `string` |  | Placeholder of empty cells. |
| `getCellLabel` | `(index: number, length: number) => string` | `Character {i} of {n}` | Accessible name of each cell. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Cell size. |
| `invalid / disabled / required` | `boolean` |  | States; inside a Field they come from it. |
| `autoFocus` | `boolean` | `false` | Focus the first empty cell on mount. |
| `name` | `string` |  | Hidden input with the whole code. |

## Styling

| Class | Element |
|---|---|
| `.mrd-pin-input` | Group (`data-size`, `data-invalid`, `data-disabled`) |
| `.mrd-pin-input__cell` | Each `<input>` (`data-filled`) |

## Accessibility

Each cell is a labelled text input ("Character 1 of 6") inside a named group, and the first cell has `autocomplete="one-time-code"` so browsers can offer the SMS code. Codes never contain gaps: typing past the end of the code writes into the first empty cell.

| Keys | Action |
| --- | --- |
| `0–9` `A–Z` | Fill the cell and move to the next. |
| `Backspace` | Clear the cell, or the previous one when empty, and move back. |
| `Delete` | Remove the character in the cell; later characters shift back. |
| `ArrowLeft` `ArrowRight` | Previous / next cell (reversed in RTL). |
| `Home` `End` | First cell / last filled cell. |

## Related

- [Input](https://meridui.dev/docs/components/input) — for codes people copy rather than type.
- [Authentication pattern](https://meridui.dev/docs/patterns/authentication).

---

# Popover

A non-modal floating panel anchored to its trigger. Escape or an outside press closes it.

## Import

```tsx
import { Popover } from "@meridui/react";
```

```tsx
<Popover.Root>
  <Popover.Trigger asChild>
    <Button variant="secondary">Share</Button>
  </Popover.Trigger>
  <Popover.Content aria-label="Share">
    <p>Anyone with the link can view this page.</p>
    <Popover.Close asChild>
      <Button variant="primary" size="sm">Copy link</Button>
    </Popover.Close>
  </Popover.Content>
</Popover.Root>
```

## Anatomy

```tsx
<Popover.Root>
  <Popover.Trigger />
  <Popover.Content>
    <Popover.Close />
  </Popover.Content>
</Popover.Root>
```

- **Root** holds the open state.
- **Trigger** is the `<button>` the panel is anchored to. Pass `asChild` to anchor to your own element, such as a `Button`.
- **Content** is the floating panel, portalled and positioned with collision handling.
- **Close** is an unstyled button that closes the popover and returns focus to the trigger. Pass `asChild` to render your own `Button`.

## Examples

### Placement

`placement` accepts any Floating UI placement (`top`, `bottom-start`, `left-end`…). It flips and shifts to stay on screen.

```tsx
<Popover.Content placement="top">Placed top</Popover.Content>
<Popover.Content placement="right">Placed right</Popover.Content>
<Popover.Content placement="bottom">Placed bottom</Popover.Content>
<Popover.Content placement="left">Placed left</Popover.Content>
```

### Controlled

```tsx
const [open, setOpen] = useState(false);

<Popover.Root open={open} onOpenChange={setOpen}>
  <Popover.Trigger asChild>
    <Button variant="secondary">Details</Button>
  </Popover.Trigger>
  <Popover.Content aria-label="Details">Open: {String(open)}</Popover.Content>
</Popover.Root>
<span>{open ? "Open" : "Closed"}</span>
```

## API reference

### Popover.Root

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` |  | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the open state should change. |
| `children` | `ReactNode` |  | Trigger and Content. |

### Popover.Trigger

Accepts every `<button>` attribute. `type` defaults to `"button"` (not set when `asChild` is used).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | `false` | Render the single child element (e.g. your own `Button`) instead of a `<button>`, merging props, ref and handlers. |
| `ref` | `Ref<HTMLButtonElement>` |  | Forwarded ref to the button. |

### Popover.Content

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `Placement` | `"bottom-start"` | Preferred placement relative to the trigger. |
| `sideOffset` | `number` | `8` | Distance from the trigger in px. |
| `aria-label` | `string` |  | Accessible name when the content has no visible heading. |
| `container` | `Element \| null` | `document.body` | Portal target. `undefined` uses `document.body`; `null` renders nothing until the target exists. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the content element. |

### Popover.Close

Accepts every `<button>` attribute.

## Styling

`.mrd-popover` is the panel: `--mrd-surface`, 1px `--mrd-line` border, `--mrd-radius-xl`, `--mrd-shadow-lg`, max width `min(360px, 100vw - 16px)`. It carries `data-state="open"`; the trigger carries `data-state="open" | "closed"`. Trigger and Close are unstyled buttons; pass `asChild` with a `Button` to style them.

## Accessibility

Content has `role="dialog"` (non-modal); the trigger has `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. Focus moves into the panel on open but is not trapped. See the [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) for the modal counterpart. Give Content an `aria-label` or a visible heading with `aria-labelledby`.

| Keys | Action |
| --- | --- |
| `Space` `Enter` | On the trigger, toggles the popover. |
| `Tab` | Moves through the popover's content, then out of it. |
| `Esc` | Closes the popover and returns focus to the trigger. |

## Guidelines

- **Do:** Use a popover for small, optional content tied to one control: sharing, quick settings, details.
- **Don't:** Put a primary task or long form in a popover; use a Dialog.

## Related

- [Tooltip](https://meridui.dev/docs/components/tooltip) for short, non-interactive labels.
- [DropdownMenu](https://meridui.dev/docs/components/dropdown-menu) for lists of actions.
- [Dialog](https://meridui.dev/docs/components/dialog)

---

# Portal

Renders its children into `document.body`, or another element, outside the parent DOM tree.

```tsx
portalBasicCode
```

## Import

```tsx
import { Portal } from "@meridui/react";
```

## Anatomy

`Portal` is a single component with no markup of its own. Dialog, AlertDialog, Drawer, Popover, Tooltip, DropdownMenu, Select and Toast already portal their content; use `Portal` directly only for your own floating layers.

## Examples

### Custom container

Pass `container` to render into a specific element instead of `document.body`.

```tsx
portalContainerCode
```

> `container={undefined}` (the default) renders into `document.body`. `container={null}` — for example before a callback ref has run — renders nothing until the element is set, so content never flashes into the wrong place.

### Theme, accent, density and direction

Portalled content leaves its DOM subtree, so it would lose a `data-theme`, `data-accent`, `data-density` or `dir` set on an ancestor. Merid's overlays (Dialog, AlertDialog, Drawer, Popover, DropdownMenu, Select, Tooltip) copy the nearest ancestor values of those attributes from their trigger (for dialogs: the element that had focus when they opened) onto a `display: contents` `.mrd-portal` wrapper, so a dark card's menu opens dark and a violet section's select stays violet. Values on `<html>` or `<body>` are not copied; the portal inherits those directly. Toasts portal from the provider and follow `<html>`; the plain `Portal` component renders its children as they are.

### Server rendering

`Portal` renders nothing on the server, during hydration and while `container` is `null`, then mounts on the client. Don't put content in a portal that must be in the initial HTML.

## API reference

### Portal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | Content rendered into the portal. |
| `container` | `Element \| null` | `document.body` | Target element. `undefined` uses `document.body`; `null` renders nothing. |

## Styling

`Portal` adds no classes, attributes or CSS variables. Content inside it is still in the React tree (context and events bubble through React), but CSS inherits from the target element, so portalled content is outside any ancestor `overflow`, `transform` or stacking context.

## Accessibility

Portal is a utility, not a widget, so there is no APG pattern. It changes DOM order, which is also reading and `Tab` order: when portalled content is interactive, manage focus yourself as the [APG dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) describes, or use one of Merid's overlay components, which already do.

Portal has no keyboard interactions of its own.

## Guidelines

- **Do:** Use Portal to escape overflow: hidden or a stacking context for floating UI.
- **Don't:** Portal inline content that belongs in reading order — it will be read at the end of the page.

## Related

- [Dialog](https://meridui.dev/docs/components/dialog)
- [Popover](https://meridui.dev/docs/components/popover)
- [Toast](https://meridui.dev/docs/components/toast)

---

ProgressDemo,
  ProgressSizes,
  ProgressIndeterminate,
  ProgressValueText,
  ProgressLive,
} from "@/examples/progress";

# Progress

A linear bar that shows how far a task has got — an upload, an export, an onboarding checklist. Without a value it becomes an indeterminate loading bar.

```tsx
<Progress aria-label="Upload" value={64} />
```

## Import

```tsx
import { Progress } from "@meridui/react";
```

## Examples

### Sizes

`sm` 4px, `md` 6px (default), `lg` 8px thick.

```tsx
<Progress aria-label="Small" size="sm" value={40} />
<Progress aria-label="Medium" size="md" value={60} />
<Progress aria-label="Large" size="lg" value={80} />
```

### Indeterminate

Omit `value` (or pass `null`) when the duration is unknown.

```tsx
<Progress aria-label="Preparing export" />
```

### Custom max and value text

`max` changes the scale; `valueText` replaces the default percentage that screen readers announce.

```tsx
<Progress aria-label="Onboarding" value={3} max={5} valueText="3 of 5 steps" />
```

### Updating

Values are clamped between 0 and `max`. The bar reaches `data-state="complete"` at 100%.

```tsx
const [value, setValue] = useState(0);
// update value as work completes

<Progress aria-label="Syncing" value={value} />
```

## API reference

Renders a `div` with `role="progressbar"`; the ref and other div attributes are forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | `null` | Current value. Omit or pass null for an indeterminate bar. |
| `max` | `number` | `100` | Maximum value. Non-positive values fall back to 100. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Bar thickness: sm 4px, md 6px, lg 8px. |
| `valueText` | `string` |  | Human-readable value for AT, e.g. "3 of 5 steps". Defaults to the percentage. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-progress` | Track |
| `.mrd-progress__bar` | Filled bar |
| `data-size` | `sm` · `md` · `lg` |
| `data-state` | `loading` · `complete` · `indeterminate` |

Component variables: `--mrd-progress-height` (set per size) and `--mrd-progress-value` (the fill percentage, set inline).

## Accessibility

- `role="progressbar"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and `aria-valuetext`. In the indeterminate state no `aria-value*` attribute is set.
- Always name the bar with `aria-label` or `aria-labelledby` — the element has no text of its own.
- Under `prefers-reduced-motion` the indeterminate animation is removed.

## Guidelines

- **Do:** Use a determinate bar when you can measure progress, and pair it with a visible label of what is happening.
- **Don't:** Fake progress with a timer that stalls at 99% — use the indeterminate bar or a [Spinner](https://meridui.dev/docs/components/spinner).

## Related

- [Spinner](https://meridui.dev/docs/components/spinner) — compact indeterminate indicator.
- [Skeleton](https://meridui.dev/docs/components/skeleton) — placeholder while content loads.
- [Stepper](https://meridui.dev/docs/components/stepper) — progress through named steps.

---

# Radio

Choose exactly one option from a small, visible set. `Radio` is a native radio input; `RadioGroup` supplies the shared `name`, the selected value and arrow-key navigation.

```tsx
<RadioGroup aria-label="Plan" defaultValue="team">
  <Radio value="free">Free</Radio>
  <Radio value="team">Team</Radio>
  <Radio value="business">Business</Radio>
</RadioGroup>
```

## Import

```tsx
import { Radio, RadioGroup } from "@meridui/react";
```

## Examples

### Controlled, with descriptions

`defaultValue` makes the group uncontrolled. For controlled use pass `value` and `onValueChange`, which receives the new value as a string. `description` adds a linked second line.

```tsx
const [value, setValue] = useState("standard");

<RadioGroup aria-label="Shipping" value={value} onValueChange={setValue}>
  <Radio value="standard" description="3–5 business days">Standard</Radio>
  <Radio value="express" description="Next business day">Express</Radio>
</RadioGroup>
```

### Horizontal

```tsx
<RadioGroup aria-label="Billing period" orientation="horizontal" defaultValue="monthly">
  <Radio value="monthly">Monthly</Radio>
  <Radio value="yearly">Yearly</Radio>
</RadioGroup>
```

### Disabled and invalid

`disabled` on the group disables every radio; on a single `Radio` it disables just that option, which arrow keys then skip. `invalid` marks the group with `aria-invalid` and turns the circles red.

```tsx
<RadioGroup aria-label="Disabled group" disabled defaultValue="a">…</RadioGroup>

<RadioGroup aria-label="Size" defaultValue="m">
  <Radio value="s">Small</Radio>
  <Radio value="m">Medium</Radio>
  <Radio value="l" disabled>Large (sold out)</Radio>
</RadioGroup>

<RadioGroup aria-label="Invalid group" invalid required>
  <Radio value="yes">Yes</Radio>
  <Radio value="no">No</Radio>
</RadioGroup>
```

## API reference

### RadioGroup

Renders a `div` with `role="radiogroup"`; the ref and other div attributes are forwarded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Selected value (controlled). |
| `defaultValue` | `string` |  | Initially selected value (uncontrolled). |
| `onValueChange` | `(value: string) => void` |  | Called with the new value when the selection changes. |
| `name` | `string` |  | Form field name shared by every radio. Generated when omitted. |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout direction. |
| `disabled` | `boolean` | `false` | Disables every radio in the group. Inside a `Field`, inherited from it. |
| `required` | `boolean` | `false` | Marks the group required for form validation. Inside a `Field`, inherited from it. |
| `invalid` | `boolean` | `false` | Marks the group invalid (`aria-invalid`; `data-invalid` on the group and each input). Inside a `Field`, derived from its `error`. |
| `children` | `ReactNode` |  | Radio elements. |

### Radio

The ref and native input attributes go to the `<input>`; `className` and `style` go to the outer wrapper.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Value submitted and reported to RadioGroup.onValueChange. |
| `children` | `ReactNode` |  | Visible label next to the circle. |
| `description` | `ReactNode` |  | Secondary line under the label, linked via aria-describedby. |
| `disabled` | `boolean` |  | Disables this radio. Defaults to the group's disabled. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-radio-group` | Group container; `data-orientation` = `vertical` · `horizontal` |
| `.mrd-radio` | Radio wrapper; `data-disabled` when disabled |
| `.mrd-radio__control`, `__input`, `__circle` | Native input and its drawn circle |
| `.mrd-radio__text`, `__label`, `__description` | Label column |
| `data-invalid` | On the group and each input; styles the circles as invalid |

Radio has no component variables.

## Accessibility

- The group has `role="radiogroup"`. Name it with `aria-label` or `aria-labelledby` pointing at a visible heading. Inside a `Field`, it is named by the Field label and picks up its description, error, required and disabled state.
- The group is a single tab stop: Tab lands on the selected radio (or the first one when nothing is selected).
- Arrow keys move focus and selection together and wrap at the ends; disabled radios are skipped. Left/Right are mirrored in right-to-left layouts.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus into the group, onto the selected radio. |
| `↓` `→` | Selects the next enabled radio, wrapping to the first. |
| `↑` `←` | Selects the previous enabled radio, wrapping to the last. |
| `Home` | Selects the first enabled radio. |
| `End` | Selects the last enabled radio. |
| `Space` | Selects the focused radio if it is not already selected. |

## Guidelines

- **Do:** Use radios for two to six options that people should compare side by side, with a sensible default selected.
- **Don't:** Use radios for long lists — use [NativeSelect](https://meridui.dev/docs/components/native-select) — or for a single yes/no, which is a checkbox.

## Related

- [SegmentedControl](https://meridui.dev/docs/components/segmented-control) — compact single-select for view switches.
- [Checkbox](https://meridui.dev/docs/components/checkbox) — independent choices.
- [NativeSelect](https://meridui.dev/docs/components/native-select) — many options.

---

# ScrollArea

A scroll container with thin, token-coloured scrollbars. Scrolling stays native: wheel, touch, keyboard, find-in-page and scroll anchoring all work, and nothing is re-implemented in JavaScript.

```tsx
scrollAreaBasicCode
```

## Import

```tsx
import { ScrollArea } from "@meridui/react";
```

## Examples

### Horizontal, scrollbar on hover

`orientation` picks the axis (`"vertical"`, `"horizontal"` or `"both"`). `autoHide` shows the scrollbar only while the area is hovered or has focus, on devices with a fine pointer.

```tsx
scrollAreaHorizontalCode
```

## API reference

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | Which axes scroll. |
| `maxHeight` | `CSSProperties["maxHeight"]` |  | Maximum height before it scrolls, e.g. 240 or "50vh". |
| `autoHide` | `boolean` | `false` | Show the scrollbar only while hovered or focused (fine pointers). |
| `label` | `string` | `"Scrollable content"` | Accessible name used when the area becomes a focusable region. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the scrolling element. |

## Styling

| Class | Element |
|---|---|
| `.mrd-scroll-area` | The scrolling element |

| Attribute / variable | Values |
|---|---|
| `data-orientation` | `vertical`, `horizontal`, `both` |
| `data-autohide` | present with `autoHide` |
| `--mrd-scroll-thumb` | thumb colour; defaults to `--mrd-line-strong` |

The scrollbar uses `scrollbar-width: thin` and `scrollbar-color` (plus `::-webkit-scrollbar` for older Safari). In forced-colours mode the system scrollbar is used.

## Accessibility

When the content overflows and contains nothing focusable, the area becomes `role="region"` with `tabIndex={0}` and the `label` as its name, so keyboard users can reach it and scroll with the arrow keys (WCAG 2.1.1). When it holds links or buttons it stays out of the Tab order: focusing those scrolls the area.

| Keys | Action |
| --- | --- |
| `ArrowUp` `ArrowDown` | Scroll vertically (browser default, once the area has focus). |
| `ArrowLeft` `ArrowRight` | Scroll horizontally. |
| `PageUp` `PageDown` | Scroll by a page. |
| `Home` `End` | Scroll to the start or end. |

## Related

- [Table](https://meridui.dev/docs/components/table): has its own horizontal scroll frame (`scrollLabel`).
- [Command](https://meridui.dev/docs/components/command): its list scrolls natively in the same way.

---

# Section

A full-bleed page band with generous vertical padding. Alternate `default` and `tray` sections to separate regions of a page by surface instead of borders.

```tsx
<Section tone="tray" spacing="compact">
  <Container>
    <Heading level={2} size="h3">Pricing</Heading>
    <Text tone="muted">One plan, billed monthly.</Text>
  </Container>
</Section>
```

## Import

```tsx
import { Section } from "@meridui/react";
```

## Examples

### Tones

`default` uses the page background; `tray` uses `--mrd-tray` for a recessed alternate band. Alternating the two is how a long page gets structure without dividers.

```tsx
<Section spacing="compact">
  <Container><Text>Default tone: the page background.</Text></Container>
</Section>
<Section tone="tray" spacing="compact">
  <Container><Text>Tray tone: the recessed alternate band.</Text></Container>
</Section>
```

### Spacing

`default` padding is `--mrd-section` (112px, stepping down to 80px and 64px on smaller screens). `compact` halves it; `none` removes it when you need the band only for its background.

```tsx
<Section tone="tray" spacing="compact">…</Section>
<Section spacing="none">…</Section>
```

### Cards on a tray section

A `tray` card would disappear on a tray section, so inside `Section tone="tray"` Merid flips tray cards to the surface colour. Use `variant="elevated"` for cards that should read as lifted.

```tsx
<Section tone="tray">
  <Container>
    <Card variant="elevated">…</Card>
  </Container>
</Section>
```

## API reference

`Section` renders a `<section>` by default, forwards its ref and passes other HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "tray"` | `"default"` | Background: page bg or the recessed tray. |
| `spacing` | `"default" \| "compact" \| "none"` | `"default"` | Vertical padding: --mrd-section, half of it, or none. |
| `as` | `ElementType` | `"section"` | Element or component to render instead. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-section` | Root element |
| `data-tone` | `default` · `tray` |
| `data-spacing` | `default` · `compact` · `none` |

Padding comes from the global `--mrd-section` token; override it on the element to change the rhythm of one band.

```css
.hero.mrd-section {
  --mrd-section: 160px;
}
```

## Accessibility

- A `<section>` is only exposed as a landmark when it has an accessible name. Give important bands an `aria-labelledby` pointing at their heading.
- Use `as="div"` for purely visual bands that do not start a new topic.

## Guidelines

- **Do:** Alternate `default` and `tray` sections to separate page regions.
- **Don't:** Stack two tray sections back to back, or add borders between sections.

## Related

- [Container](https://meridui.dev/docs/components/container) — caps the width of content inside a section.
- [Card](https://meridui.dev/docs/components/card) — surfaces that adapt to a tray section.
- [Stack](https://meridui.dev/docs/components/stack) — spacing between blocks within a section.

---

SegmentedControlDemo,
  SegmentedControlControlled,
  SegmentedControlIcons,
  SegmentedControlStates,
} from "@/examples/segmented-control";

# SegmentedControl

A pill-shaped single-select toggle for switching between a few views, ranges or modes. It behaves as a radio group: one tab stop, arrow keys to move.

```tsx
<SegmentedControl
  aria-label="Range"
  defaultValue="week"
  options={[
    { value: "day", label: "Day" },
    { value: "week", label: "Week" },
    { value: "month", label: "Month" },
  ]}
/>
```

## Import

```tsx
import { SegmentedControl, type SegmentedControlOption } from "@meridui/react";
```

## Examples

### Controlled

Uncontrolled, the control starts on `defaultValue` or the first enabled option. For controlled use pass `value` and `onValueChange`.

```tsx
const [value, setValue] = useState("month");

<SegmentedControl aria-label="Range" options={range} value={value} onValueChange={setValue} />
```

### Icon segments

When a segment's `label` is an icon, give the option an `ariaLabel`.

```tsx
<SegmentedControl
  aria-label="View"
  options={[
    { value: "list", label: <ListIcon />, ariaLabel: "List view" },
    { value: "grid", label: <GridIcon />, ariaLabel: "Grid view" },
  ]}
/>
```

### Disabled options, disabled control, full width

```tsx
<SegmentedControl
  aria-label="Plan"
  options={[
    { value: "monthly", label: "Monthly" },
    { value: "yearly", label: "Yearly" },
    { value: "lifetime", label: "Lifetime", disabled: true },
  ]}
/>
<SegmentedControl aria-label="Range" options={range} disabled />
<SegmentedControl aria-label="Range" options={range} fullWidth />
```

## API reference

### SegmentedControl

The ref and other div attributes go to the `role="radiogroup"` container.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `SegmentedControlOption[]` |  | The segments. |
| `value` | `string` |  | Selected value (controlled). |
| `defaultValue` | `string` |  | Initially selected value (uncontrolled). Defaults to the first enabled option. |
| `onValueChange` | `(value: string) => void` |  | Called with the new value when the selection changes. |
| `fullWidth` | `boolean` | `false` | Stretches segments to fill the container. |
| `disabled` | `boolean` | `false` | Disables the whole control. |

### SegmentedControlOption

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Value reported on selection. |
| `label` | `ReactNode` |  | Visible content of the segment. |
| `ariaLabel` | `string` |  | Accessible name when label is not text (e.g. an icon). |
| `disabled` | `boolean` |  | Makes the segment unselectable and skipped by arrow keys. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-segmented` | Pill track; `data-full-width` when stretched |
| `.mrd-segmented__item` | Each segment {"<button role=\"radio\">"} |
| `data-state` | `on` · `off` on each item |

On a tray section or tray card the track switches to `--mrd-tray-2` automatically. There are no component variables.

## Accessibility

- The container is `role="radiogroup"`, each segment `role="radio"` with `aria-checked`. Name the group with `aria-label` or `aria-labelledby`.
- Only the selected segment is in the tab order. Arrow keys move and select at once (APG radio group), skipping disabled segments and wrapping at the ends.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the selected segment. |
| `→` `↓` | Selects the next enabled segment. |
| `←` `↑` | Selects the previous enabled segment. |
| `Home` | Selects the first enabled segment. |
| `End` | Selects the last enabled segment. |

## Guidelines

- **Do:** Use two to five short, parallel labels that switch a view in place: Day / Week / Month.
- **Don't:** Use it for navigation between pages, or for panels with their own content — that is [Tabs](https://meridui.dev/docs/components/tabs).

## Related

- [Tabs](https://meridui.dev/docs/components/tabs) — switch between content panels.
- [Radio](https://meridui.dev/docs/components/radio) — single choice with longer labels or descriptions.
- [Switch](https://meridui.dev/docs/components/switch) — a single on/off setting.

---

SelectBasic,
  SelectControlled,
  SelectSizes,
} from "@/examples/select";

# Select

Choose one option from a styled list.

```tsx
selectBasicCode
```

## Import

```tsx
import { Select } from "@meridui/react";
```

## Anatomy

```tsx
<Select.Root>
  <Select.Trigger />
  <Select.Content>
    <Select.Item value="a">A</Select.Item>
  </Select.Content>
</Select.Root>
```

- **Root** holds the value and open state, and renders a hidden `<input>` when `name` is set.
- **Trigger** is the `role="combobox"` button. It shows the selected label or the placeholder.
- **Content** is the portalled `role="listbox"`. It stays mounted (hidden) so options can report their labels.
- **Item** is one `role="option"`. Its text children are the label, shown in the trigger and used for typeahead.

## Examples

### Controlled

Pass `value` and `onValueChange`. An empty string means nothing is selected and shows the `placeholder`.

```tsx
selectControlledCode
```

### Sizes and disabled

```tsx
selectSizesCode
```

### In a form

Set `name` (and optionally `required` and `form`) on Root. A hidden input carries the value on submit.

```tsx
<form>
  <Select.Root name="region" required>
    <Select.Trigger aria-label="Region" />
    <Select.Content>…</Select.Content>
  </Select.Root>
</form>
```

## API reference

### Root

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Controlled selected value ("" means nothing selected). |
| `defaultValue` | `string` | `""` | Initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called with the newly selected value. |
| `open` | `boolean` |  | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the open state should change. |
| `name` | `string` |  | Form field name; renders a hidden input carrying the value. |
| `required` | `boolean` |  | Marks the hidden input as required. |
| `disabled` | `boolean` | `false` | Disable the whole select. |
| `placeholder` | `ReactNode` | `"Select…"` | Shown in the trigger when no value is selected. |
| `form` | `string` |  | Associates the hidden input with a form by id. |
| `children` | `ReactNode` |  | Trigger and Content. |

### Trigger

Accepts every `<button>` attribute except `value`. Children, when given, replace the displayed label. An `id` you pass is kept (so `<label htmlFor>` works) and the listbox stays labelled by it. Inside a [Field](https://meridui.dev/docs/components/field) the trigger picks up the wiring like every Merid control: the field's id and label (`aria-labelledby`), `aria-describedby` for the description and error, `aria-invalid` + `data-invalid`, `aria-required` and `disabled`. Explicit props win.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control size. |
| `invalid` | `boolean` |  | Marks the field invalid: `aria-invalid` for semantics, `data-invalid` for the danger border. Inside a Field, derived from its error. |
| `ref` | `Ref<HTMLButtonElement>` |  | Forwarded ref to the combobox button. |

### Content

Accepts every `<div>` attribute. The listbox matches the trigger's width.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `Placement` | `"bottom-start"` | Preferred placement. |
| `sideOffset` | `number` | `6` | Distance from the trigger in px. |
| `container` | `Element \| null` | `document.body` | Portal target. `undefined` uses `document.body`; `null` renders nothing until the target exists. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the listbox. |

### Item

Accepts every `<div>` attribute except `children`. Your `onClick` and `onPointerMove` run first; call `event.preventDefault()` in them to skip selecting or highlighting the option.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Value submitted and reported by onValueChange. |
| `children` | `string` |  | Visible label. Also used in the trigger and for typeahead. |
| `disabled` | `boolean` | `false` | Disable the option. |

## Styling

| Class | Element |
|---|---|
| `.mrd-select__trigger` | Trigger |
| `.mrd-select__value`, `.mrd-select__icon` | Trigger label and chevron |
| `.mrd-select__content` | Listbox |
| `.mrd-select__item`, `.mrd-select__item-text`, `.mrd-select__check` | Option, its text, the selected check |

| Attribute | On | Values |
|---|---|---|
| `data-state` | Trigger, Content | `open`, `closed` |
| `data-size` | Trigger | `sm`, `md`, `lg` |
| `data-placeholder` | Trigger | present when no value is selected |
| `data-invalid` | Trigger | present when invalid (drives the danger border) |
| `data-active` | Item | present on the keyboard/pointer-highlighted option |
| `data-disabled` | Item | present when disabled |
| `aria-selected="true"` | Item | the selected option |

The trigger height comes from `--mrd-select-height`, set per `data-size`.

## Accessibility

Follows the WAI-ARIA [Select-Only Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/). Focus stays on the trigger; the highlighted option is exposed through `aria-activedescendant`. Give the trigger an accessible name with `aria-label`, `aria-labelledby`, or an `id` referenced by a `<label htmlFor>`.

| Keys | Action |
| --- | --- |
| `Enter` | Open, or select the highlighted option and close. |
| `Space` | Open, or select the highlighted option and close. |
| `ArrowDown` | Open, or highlight the next option. |
| `ArrowUp` | Open, or highlight the previous option. |
| `Home` | Highlight the first option. |
| `End` | Highlight the last option. |
| `A–Z` | Typeahead. When closed, selects the match directly. |
| `Tab` | Select the highlighted option, close and move focus on. |
| `Escape` | Close without changing the value. |

## Guidelines

- **Do:** Use Select for 5–15 options where the list itself is familiar (countries, regions, plans).
- **Don't:** Use Select for two or three options — show them as [Radio](https://meridui.dev/docs/components/radio) or a [SegmentedControl](https://meridui.dev/docs/components/segmented-control).

- **Do:** Always pair the trigger with a visible label.
- **Don't:** Rely on the placeholder as the only label; it disappears once a value is chosen.

## Related

- [NativeSelect](https://meridui.dev/docs/components/native-select) — the platform `<select>`, best on mobile and for long lists.
- [DropdownMenu](https://meridui.dev/docs/components/dropdown-menu) — actions, not values.
- [Field](https://meridui.dev/docs/components/field) — label, hint and error around a control.

---

# Separator

A 1px `--mrd-line` hairline that divides content. Reach for spacing or a surface change first; use a separator when neither is enough.

```tsx
<Text weight="medium" tone="ink">Account</Text>
<Separator />
<Text size="sm">Profile, email and password.</Text>
```

## Import

```tsx
import { Separator } from "@meridui/react";
```

## Examples

### Vertical

`orientation="vertical"` draws a vertical line that stretches to its flex container's height.

```tsx
<Stack direction="row" gap={3} align="center">
  <Text size="sm" as="span">Docs</Text>
  <Separator orientation="vertical" />
  <Text size="sm" as="span">Changelog</Text>
  <Separator orientation="vertical" />
  <Text size="sm" as="span">GitHub</Text>
</Stack>
```

### Semantic separator

By default the line is decorative (`role="none"`). Set `decorative={false}` when it divides meaningful groups, so it is exposed as `role="separator"`.

```tsx
<Text size="sm">Recent files</Text>
<Separator decorative={false} />
<Text size="sm">Shared with you</Text>
```

## API reference

Renders a `div`; forwards its ref and passes native attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the hairline. |
| `decorative` | `boolean` | `true` | When true the line is purely visual (role="none"). Set false to expose role="separator". |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-separator` | Root ` ` |
| `data-orientation` | `horizontal` · `vertical` |

Separator has no component variables; its colour is `--mrd-line`. Add spacing with margin on the separator or gap on the parent.

## Accessibility

- Decorative separators are removed from the accessibility tree.
- With `decorative={false}`, the element has `role="separator"`, and vertical separators also get `aria-orientation="vertical"`.

## Guidelines

- **Do:** Separate groups with whitespace or a tray surface first, and keep separators for dense lists and toolbars.
- **Don't:** Stack separators between every paragraph or make them thicker or darker than 1px `--mrd-line`.

## Related

- [Stack](https://meridui.dev/docs/components/stack) — gap-based spacing, often a better divider.
- [Section](https://meridui.dev/docs/components/section) — separates page bands by surface.

---

# Shortcut

A key combination such as ⌘K or Ctrl+K, built from [Kbd](https://meridui.dev/docs/components/kbd) key caps. `mod` becomes ⌘ on macOS and Ctrl elsewhere, and screen readers hear the full key names.

```tsx
<Text>
  Press <Shortcut keys={["mod", "k"]} /> to search, or <Shortcut keys={["mod", "shift", "p"]} /> for commands.
</Text>
```

## Import

```tsx
import { Shortcut, formatShortcut, matchesShortcut } from "@meridui/react";
```

## Examples

### Platforms and sizes

The platform is detected after hydration (the server renders the non-Mac form). Force it with `platform`. Keys: `mod`, `ctrl`, `meta`, `alt`, `shift`, `enter`, `escape`, `tab`, `backspace`, `delete`, `space`, the arrows (`arrowup`…) and any single character.

```tsx
<Shortcut keys={["mod", "shift", "z"]} platform="mac" />
<Shortcut keys={["mod", "shift", "z"]} platform="other" />
<Shortcut keys={["alt", "arrowup"]} platform="mac" size="sm" />
<Shortcut keys={["alt", "arrowup"]} platform="other" size="sm" />
```

### Matching key presses

`matchesShortcut(event, keys)` uses the same rules, so what you show and what you handle never drift apart. Modifiers must match exactly.

```tsx
useEffect(() => {
  const onKeyDown = (event: KeyboardEvent) => {
    if (matchesShortcut(event, ["mod", "s"])) {
      event.preventDefault();
      save();
    }
  };
  document.addEventListener("keydown", onKeyDown);
  return () => document.removeEventListener("keydown", onKeyDown);
}, []);
```

`formatShortcut(["mod", "k"])` returns the plain string (`"⌘K"` or `"Ctrl+K"`) for places that only take text, like a `title` or an `aria-keyshortcuts` hint.

## API reference

Accepts every `<kbd>` attribute except `children`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` | `string[]` |  | Keys pressed together, e.g. ["mod", "k"]. |
| `platform` | `"auto" \| "mac" \| "other"` | `"auto"` | Force a platform; auto detects it after hydration. |
| `size` | `"sm" \| "md"` | `"md"` | Key cap size. |
| `labels` | `Record<string, string>` |  | Spoken key names merged over the English defaults, e.g. { shift: "Üst karakter" }. Keys ending in .mac or .other apply to one platform. |
| `joiner` | `string` | `"+"` | Word read between keys by screen readers. |
| `ref` | `Ref<HTMLElement>` |  | Forwarded ref to the outer <kbd>. |

### Helpers

| Function | Returns |
|---|---|
| `formatShortcut(keys, platform?)` | `"⌘K"` / `"Ctrl+K"` |
| `matchesShortcut(event, keys, platform?)` | `true` when the event presses exactly `keys` |
| `keySymbol(key, platform)`, `keyLabel(key, platform, labels?)` | One key's symbol or spoken name |
| `detectPlatform()`, `usePlatform()` | `"mac"` or `"other"` |

## Styling

Shortcut is a `.mrd-kbd` with `.mrd-shortcut`; each key is a nested `<kbd class="mrd-shortcut__key">`. On non-Mac platforms a muted `+` is drawn between keys with CSS. `data-platform` and `data-size` are set on the outer element.

## Accessibility

Nested `<kbd>` elements are the HTML way to mark up a key combination. The visible symbols (⌘, ⇧, ⌥) are hidden from assistive technology and replaced by visually hidden names ("Command + Shift + P"), which you can translate with `labels`.

## Related

- [Kbd](https://meridui.dev/docs/components/kbd): a single key cap.
- [Command](https://meridui.dev/docs/components/command): shows item shortcuts with this component.

---

# SidebarNav

Vertical navigation for application sidebars, with groups, icons and trailing counts.

```tsx
sidebarNavBasicCode
```

## Import

```tsx
import { SidebarNav } from "@meridui/react";
```

`SidebarNavItem` is also exported on its own and is the same component as `SidebarNav.Item`.

## Anatomy

```tsx
<SidebarNav aria-label="…">
  <SidebarNav.Item href="…" icon={…} trailing={…} active />
  <SidebarNav.Group label="…">
    <SidebarNav.Item href="…" />
  </SidebarNav.Group>
</SidebarNav>
```

- `SidebarNav` (also `SidebarNav.Root`) — a `<nav>` with a list.
- `SidebarNav.Item` — a link wrapped in its own `<li>`, with optional icon and trailing element.
- `SidebarNav.Group` — an `<li>` with a visible label that names a nested list.

## Examples

### With a router

Pass your router's link component through `as`. Extra props are forwarded to it.

## API reference

### SidebarNav

Renders `<nav>` and accepts all its HTML attributes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Accessible name of the landmark (required when a page has several navs). |
| `ref` | `Ref<HTMLElement>` |  | Forwarded ref to the nav element. |

### SidebarNav.Item

Renders `<a>` (or `as`) inside an `<li>` and accepts all anchor attributes plus any props for `as`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Marks the current page: sets aria-current="page" and the selected style. |
| `icon` | `ReactNode` |  | Icon shown before the label (decorative). |
| `trailing` | `ReactNode` |  | Trailing element such as a count Badge. |
| `as` | `ElementType` | `"a"` | Element or component to render instead of <a>, e.g. a router Link. |
| `ref` | `Ref<HTMLAnchorElement>` |  | Forwarded ref to the link. |

### SidebarNav.Group

Renders `<li>` and accepts its HTML attributes except `title`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` |  | Visible group heading; also labels the nested list. |

## Styling

- `.mrd-sidebar-nav`, `.mrd-sidebar-nav__list` — root and each list, 2px gap between items.
- `.mrd-sidebar-nav__item` — the link: 36px min height (44px on coarse pointers), `--mrd-radius-md`.
- `.mrd-sidebar-nav__item[aria-current="page"]` (also `data-state="active"`) — `--mrd-accent-soft` fill with `--mrd-accent-strong` text.
- `.mrd-sidebar-nav__icon`, `.mrd-sidebar-nav__label`, `.mrd-sidebar-nav__trailing` — icon slot, truncating label, trailing slot.
- `.mrd-sidebar-nav__group`, `.mrd-sidebar-nav__group-label` — group spacing and its muted label.

## Accessibility

Follows the [APG landmark regions guidance](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/) for a `navigation` landmark; there is no widget pattern because items are plain links.

- Name the landmark with `aria-label` when the page has more than one `nav`.
- The active link has `aria-current="page"`.
- Each group's nested list is labelled by its visible heading via `aria-labelledby`.
- Icons are `aria-hidden`; the label must carry the meaning.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the next link. |
| `Shift` `Tab` | Moves focus to the previous link. |
| `Enter` | Follows the focused link. |

## Guidelines

- **Do:** Keep labels to one or two words and mark exactly one item active.
- **Don't:** Put actions such as “New project” buttons in the list; they are not destinations.

- **Do:** Use trailing for counts people act on, like unread items.
- **Don't:** Rely on the icon alone; the label is always required.

## Related

- [Breadcrumb](https://meridui.dev/docs/components/breadcrumb)
- [Tabs](https://meridui.dev/docs/components/tabs)
- [Badge](https://meridui.dev/docs/components/badge)

---

# Skeleton

A placeholder that holds the shape of content while it loads, so the layout does not jump when data arrives. It shimmers every 1.4s and stays static under reduced motion.

```tsx
<Stack direction="row" gap={3} align="center" aria-busy="true">
  <Skeleton circle width={40} height={40} />
  <Stack gap={2} style={{ flex: 1 }}>
    <Skeleton width="60%" />
    <Skeleton width="90%" height={12} />
  </Stack>
</Stack>
```

## Import

```tsx
import { Skeleton } from "@meridui/react";
```

## Examples

### Text block

Without sizing props a skeleton is full width and `1em` tall — one line of the surrounding text. Shorten the last line so the block reads as a paragraph.

```tsx
<Stack gap={2} aria-busy="true">
  <Skeleton height={24} width="50%" />
  <Skeleton />
  <Skeleton />
  <Skeleton width="75%" />
</Stack>
```

### Shapes

Numbers are pixels, strings are any CSS length. `circle` rounds fully; set equal `width` and `height`.

```tsx
<Skeleton width={120} height={80} />
<Skeleton circle width={48} height={48} />
<Skeleton width={96} height={36} />
```

## API reference

Renders an `aria-hidden` `span`; forwards its ref. `style` is merged after the sizing props, so it can override them.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number \| string` | `"100%"` | CSS width; a number is px. |
| `height` | `number \| string` | `"1em"` | CSS height; a number is px. |
| `circle` | `boolean` | `false` | Renders a circle. Set width and height equal. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-skeleton` | Root ` ` |
| `data-shape` | `rect` · `circle` |

Skeleton has no component variables. The shimmer runs from `--mrd-tray` to `--mrd-tray-2` — the one gradient Merid allows.

## Accessibility

- Every skeleton is `aria-hidden`; it says nothing to assistive tech on its own.
- Put `aria-busy="true"` on the region that is loading, and remove it when content arrives. For a spoken cue, add a visually hidden “Loading…” status.

## Guidelines

- **Do:** Mirror the real layout closely — same avatar size, same number of lines — so nothing shifts when content loads.
- **Don't:** Show skeletons for content that loads in under ~300ms, or for errors and empty results.

## Related

- [Spinner](https://meridui.dev/docs/components/spinner) — for actions rather than content.
- [EmptyState](https://meridui.dev/docs/components/empty-state) — what to show once loading finds nothing.

---

# Slider

Pick a value, or a range with two thumbs, on a horizontal track. Values snap to `step`; the track follows `dir="rtl"`.

```tsx
const [value, setValue] = useState([40]);

<span id="volume">Volume</span>
<Slider aria-labelledby="volume" value={value} onValueChange={setValue} />
```

## Import

```tsx
import { Slider } from "@meridui/react";
```

## Examples

### Range

Pass two values. Thumbs cannot cross; `minStepsBetweenThumbs` keeps them apart. Name each thumb with `thumbLabels` and give values a readable form with `getValueText`.

```tsx
<Slider
  value={value}
  onValueChange={setValue}
  min={0}
  max={1000}
  step={10}
  minStepsBetweenThumbs={5}
  thumbLabels={["Minimum price", "Maximum price"]}
  getValueText={(v) => "$" + v}
  name="price"
/>
```

### Decimal steps, disabled and RTL

```tsx
<Slider aria-label="Opacity" defaultValue={[0.5]} min={0} max={1} step={0.05} />
<Slider aria-label="Disabled" defaultValue={[30]} disabled />
<div dir="rtl">
  <Slider aria-label="RTL" defaultValue={[25]} />
</div>
```

## API reference

Renders a `div`; other `div` attributes and the ref go on it. For a single thumb, `aria-label` / `aria-labelledby` on the root name the thumb.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number[]` |  | Controlled values: one for a single slider, two for a range. |
| `defaultValue` | `number[]` | `[min]` | Initial values when uncontrolled. |
| `onValueChange` | `(value: number[]) => void` |  | Called on every change while dragging or pressing keys. |
| `onValueCommit` | `(value: number[]) => void` |  | Called when a drag ends or after a key press. |
| `min` | `number` | `0` | Lowest value. |
| `max` | `number` | `100` | Highest value. |
| `step` | `number` | `1` | Increment. |
| `largeStep` | `number` | `step * 10` | Increment for Page Up / Page Down and Shift + arrows. |
| `minStepsBetweenThumbs` | `number` | `0` | Minimum distance between range thumbs, in steps. |
| `thumbLabels` | `string[]` | `["Minimum", "Maximum"] for a range` | Accessible name of each thumb. |
| `getValueText` | `(value: number, index: number) => string` |  | aria-valuetext, e.g. with a unit or currency. |
| `disabled` | `boolean` | `false` | Disables the slider. |
| `name` | `string` |  | Hidden input per thumb: name for one thumb, name[] for a range. |

## Styling

| Class | Element |
|---|---|
| `.mrd-slider` | Root (`data-disabled`) |
| `.mrd-slider__track` | Track, and the pointer target |
| `.mrd-slider__range` | Filled part of the track |
| `.mrd-slider__thumb` | Thumb, `role="slider"` |

## Accessibility

Each thumb is a `role="slider"` with `aria-valuenow`, `aria-valuemin` and `aria-valuemax`. In a range, the limits of each thumb are the other thumb's value, so screen readers report the real bounds. The track has a 24px hit area and each thumb a 24px target (44px on coarse pointers).

| Keys | Action |
| --- | --- |
| `ArrowRight` `ArrowUp` | Increase by step (ArrowRight decreases in RTL). |
| `ArrowLeft` `ArrowDown` | Decrease by step (ArrowLeft increases in RTL). |
| `PageUp` `PageDown` | Increase / decrease by largeStep. Shift + arrows do the same. |
| `Home` `End` | Set to the minimum / maximum. |

## Related

- [NumberInput](https://meridui.dev/docs/components/number-input) — when the exact number matters.

---

# Spinner

An indeterminate loading indicator for short waits whose length is unknown. It inherits `currentColor`, so it matches whatever text or button it sits in.

```tsx
<Spinner />
```

## Import

```tsx
import { Spinner } from "@meridui/react";
```

## Examples

### Sizes

Diameters of 14px (`sm`), 18px (`md`, default) and 24px (`lg`).

```tsx
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />
```

### Next to text

When visible text already says what is loading, pass `label={null}` to hide the spinner from assistive tech so the message is not announced twice.

```tsx
<Stack direction="row" gap={2} align="center">
  <Spinner size="sm" label={null} />
  <Text size="sm" as="span">Loading invoices…</Text>
</Stack>
```

### Colour

Set `color` on the spinner or a parent. Give it a specific `label` when it stands alone.

```tsx
<span style={{ color: "var(--mrd-accent)" }}>
  <Spinner size="lg" label="Uploading" />
</span>
```

## API reference

Renders a `span`; forwards its ref and passes native attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Diameter: sm 14px, md 18px, lg 24px. |
| `label` | `string \| null` | `"Loading"` | Accessible name. Pass null when decorative — the spinner is then aria-hidden. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-spinner` | Root ` ` |
| `.mrd-spinner__svg` | The SVG |
| `.mrd-spinner__track` | Faint full circle |
| `.mrd-spinner__arc` | Rotating quarter arc |
| `data-size` | `sm` · `md` · `lg` |

Component variable: `--mrd-spinner-size`, set per size.

```css
.hero .mrd-spinner {
  --mrd-spinner-size: 32px;
}
```

## Accessibility

- With a label, the spinner has `role="status"` and `aria-label`, so screen readers announce it politely.
- With `label={null}` it is `aria-hidden`. Mark the region that is loading with `aria-busy="true"`.
- Under `prefers-reduced-motion`, the rotation slows down rather than stopping, so progress stays visible.

## Guidelines

- **Do:** Use a spinner for waits under a few seconds. For longer or measurable work, show a `Progress` bar.
- **Don't:** Replace a whole page with a spinner when a `Skeleton` could show the shape of the content that is coming.

## Related

- [Button](https://meridui.dev/docs/components/button) — `loading` shows this spinner inside the button.
- [Skeleton](https://meridui.dev/docs/components/skeleton) — placeholder for content that is loading.
- [Progress](https://meridui.dev/docs/components/progress) — for determinate progress.

---

# Stack

A one-dimensional flex layout: children in a column or a row, spaced by a gap from the `--mrd-space-*` scale. Use it instead of margins between siblings.

```tsx
<Stack gap={3}>
  <Box>1</Box>
  <Box>2</Box>
  <Box>3</Box>
</Stack>
```

## Import

```tsx
import { Stack } from "@meridui/react";
```

## Examples

### Row

```tsx
<Stack direction="row" gap={2}>
  <Box>1</Box>
  <Box>2</Box>
  <Box>3</Box>
</Stack>
```

### Alignment

`align` maps to `align-items`, `justify` to `justify-content` (`between` is `space-between`).

```tsx
<Stack direction="row" gap={2} align="center" justify="between">
  <Box>short</Box>
  <Box>tall</Box>
  <Box>mid</Box>
</Stack>
```

### Wrapping

```tsx
<Stack direction="row" gap={2} wrap>
  {tags.map((tag) => <Box key={tag}>{tag}</Box>)}
</Stack>
```

### Semantic element

Use `as` to render a list, nav or form — the layout stays the same.

```tsx
<Stack as="ul" gap={1}>
  <li>First item</li>
  <li>Second item</li>
</Stack>
```

## API reference

Renders a `div` unless `as` is given; forwards its ref and passes all HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `"row" \| "column"` | `"column"` | Main axis. |
| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 10 \| 14 \| 16 \| 18 \| 28` | `4` | Gap from the --mrd-space-* scale (4 = 16px). |
| `align` | `"start" \| "center" \| "end" \| "stretch" \| "baseline"` |  | Cross-axis alignment (align-items). |
| `justify` | `"start" \| "center" \| "end" \| "between"` |  | Main-axis distribution (justify-content). |
| `wrap` | `boolean` | `false` | Allows items to wrap onto multiple lines. |
| `as` | `ElementType` | `"div"` | Element or component to render instead of a div. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-stack` | Root element |
| `data-direction` | `row` · `column` |
| `data-align` | `start` · `center` · `end` · `stretch` · `baseline` |
| `data-justify` | `start` · `center` · `end` · `between` |
| `data-wrap` | Present when `wrap` |

Component variable: `--mrd-stack-gap`, set inline from `gap`. Override it in CSS for responsive gaps:

```css
@media (max-width: 640px) {
  .actions.mrd-stack { --mrd-stack-gap: var(--mrd-space-2); }
}
```

## Accessibility

- Stack is layout only and adds no role. Choose the right element with `as` (`ul`, `nav`, `form`).
- Visual order follows DOM order; don't reverse it with CSS, or focus order and reading order will disagree.

## Guidelines

- **Do:** Use one gap per stack and nest stacks for different rhythms.
- **Don't:** Mix `gap` with margins on children to fine-tune spacing.

## Related

- [Grid](https://meridui.dev/docs/components/grid) — two-dimensional layout.
- [Container](https://meridui.dev/docs/components/container) — caps content width.

---

# Stepper

A read-only display of progress through a multi-step flow.

```tsx
stepperBasicCode
```

## Import

```tsx
import { Stepper } from "@meridui/react";
```

## Anatomy

```tsx
<Stepper.Root current={0}>
  <Stepper.Step title="…" description="…" />
</Stepper.Root>
```

- `Stepper.Root` — an ordered list. `current` is the zero-based index of the active step; earlier steps are complete, later ones upcoming.
- `Stepper.Step` — one step with a numbered marker (a check when complete), a title and an optional description.

## Examples

### Vertical with descriptions

```tsx
stepperVerticalCode
```

### Responsive behaviour

In horizontal orientation, titles and descriptions stay on one line and truncate with an ellipsis; string titles keep the full text in a `title` attribute. The stepper measures its own width (a CSS container query, not the viewport): below 560px it switches to a compact layout where only the current step shows its title and the others collapse to their numbered or checked markers. Collapsed titles stay in the accessibility tree, so screen readers hear every step either way, and narrow columns need no JavaScript or orientation switch.

## API reference

### Stepper.Root

Renders `<ol>` and accepts all its HTML attributes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `current` | `number` |  | Zero-based index of the current step. Steps before it are complete. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction. |
| `aria-label` | `string` | `"Progress"` | Accessible name for the step list. |
| `ref` | `Ref<HTMLOListElement>` |  | Forwarded ref to the list. |

### Stepper.Step

Renders `<li>` and accepts its HTML attributes except `title`. Must be a direct child of `Stepper.Root`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  | Step name. |
| `description` | `ReactNode` |  | Optional supporting line. |
| `statusLabels` | `Partial<Record<"complete" \| "current" \| "upcoming", string>>` | `{ complete: "Completed", current: "Current step", upcoming: "Not started" }` | Screen-reader status words appended to each step. |

## Styling

- `.mrd-stepper[data-orientation]` — root list, `horizontal` or `vertical`.
- `.mrd-stepper__step[data-state]` — `complete`, `current` or `upcoming`.
- `.mrd-stepper__marker` — 28px circle: `--mrd-tray` when upcoming, a 1.5px `--mrd-accent` ring when current, `--mrd-accent-soft` when complete.
- `.mrd-stepper__title` / `.mrd-stepper__description` — text; the title turns `--mrd-ink` on the current step.
- `.mrd-stepper__step::after` — the 1px `--mrd-line` connector between steps.

## Accessibility

There is no APG pattern for steppers. It is a static ordered list — the same structure the [APG landmark and list guidance](https://www.w3.org/WAI/ARIA/apg/practices/structural-roles/) recommends for structured content — and it is not interactive.

- The list is named "Progress" by default; set `aria-label` to describe the flow.
- The current step has `aria-current="step"`.
- Each step ends with a visually hidden status word ("Completed", "Current step", "Not started"), overridable with `statusLabels` for localisation.
- Markers are `aria-hidden`; the number is conveyed by list position.

Steps are not focusable, so there are no keyboard interactions. If people can jump back to a step, put links or buttons inside the step content.

## Guidelines

- **Do:** Use short, noun-like step titles and keep the number of steps between three and six.
- **Don't:** Use a stepper as tabs or as the only way to navigate between steps.

- **Do:** Localise statusLabels along with the titles.
- **Don't:** Mark a step complete before its data is actually saved.

## Related

- [Progress](https://meridui.dev/docs/components/progress)
- [Tabs](https://meridui.dev/docs/components/tabs)
- [Pagination](https://meridui.dev/docs/components/pagination)

---

# Switch

A 34×20 on/off toggle for settings that take effect as soon as they change. It is a `<button role="switch">`, not a checkbox.

```tsx
<Switch defaultChecked>Dark mode</Switch>
```

## Import

```tsx
import { Switch } from "@meridui/react";
```

## Examples

### Controlled

`defaultChecked` keeps state inside the switch. For controlled use pass `checked` and `onCheckedChange`, which receives the next boolean.

```tsx
const [on, setOn] = useState(false);

<Switch checked={on} onCheckedChange={setOn}>
  Auto-save drafts
</Switch>
```

### Label position

```tsx
<Switch labelPosition="start">Label at start</Switch>
<Switch labelPosition="end">Label at end</Switch>
```

### Disabled and unlabelled

Without children, give the switch an `aria-label`.

```tsx
<Switch disabled>Disabled off</Switch>
<Switch disabled defaultChecked>Disabled on</Switch>
<Switch aria-label="Notifications" />
```

### In a form

A button does not submit a value on its own. Set `name` and the switch renders a hidden input that submits `value` (default `"on"`) while it is on — nothing is submitted while off.

```tsx
<form>
  <Switch name="newsletter" value="yes" defaultChecked>
    Subscribe to newsletter
  </Switch>
</form>
```

## API reference

The ref and remaining button attributes go to the track `<button>`; `className` goes to the outer wrapper.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` |  | On state (controlled). |
| `defaultChecked` | `boolean` | `false` | Initial on state (uncontrolled). |
| `onCheckedChange` | `(checked: boolean) => void` |  | Called with the new state when toggled. |
| `children` | `ReactNode` |  | Visible label; becomes the accessible name. Otherwise pass aria-label. |
| `labelPosition` | `"start" \| "end"` | `"end"` | Which side the label sits on. |
| `name` | `string` |  | When set, a hidden input with this name submits value while on. |
| `value` | `string` | `"on"` | Submitted value when on. |
| `disabled` | `boolean` |  | Disables the switch and dims the label. Inside a `Field`, inherited from it. |
| `invalid` | `boolean` |  | Forces the invalid style (`data-invalid`) and `aria-invalid`. Inside a `Field`, derived from its `error`. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-switch` | Wrapper; receives `className` |
| `.mrd-switch__track` | The {"<button role=\"switch\">"} |
| `.mrd-switch__thumb` | Moving thumb |
| `.mrd-switch__label` | Visible label |
| `data-state` | `on` · `off` (wrapper and track) |
| `data-label-position` | `start` · `end` |
| `data-disabled` | On the wrapper when disabled |
| `data-invalid` | On the track when invalid; draws the danger ring |

Switch has no component variables; the off track uses `--mrd-control-off` and the on track `--mrd-accent`.

## Accessibility

- Exposed as `role="switch"` with `aria-checked`, so screen readers announce “on” / “off”.
- The visible label is linked with `aria-labelledby`; clicking it also toggles the switch.
- Inside a `Field`, the switch takes the Field id (so the Field label names it), plus its `aria-describedby`, `aria-invalid` and `disabled`.
- `aria-invalid` carries the invalid semantics; `data-invalid` drives the styling.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the switch. |
| `Space` | Toggles the switch. |
| `Enter` | Toggles the switch. |

## Guidelines

- **Do:** Use a switch for settings that apply instantly, and label it with the setting name: “Dark mode”.
- **Don't:** Use a switch in a form that needs a Save button — use a [Checkbox](https://meridui.dev/docs/components/checkbox).

- **Do:** Keep the label static; the switch itself shows the state.
- **Don't:** Change the label between “On” and “Off” — it duplicates the state and confuses screen reader users.

## Related

- [Checkbox](https://meridui.dev/docs/components/checkbox) — choices applied on submit.
- [SegmentedControl](https://meridui.dev/docs/components/segmented-control) — pick between named modes.

---

# Table

Styled primitives for tabular data: a real `<table>` in a hairline-ringed frame that scrolls horizontally when it runs out of room. Sorting, pagination and selection logic stay in your code.

```tsx
<Table scrollLabel="Invoices">
  <TableHead>
    <TableRow>
      <TableHeader>Invoice</TableHeader>
      <TableHeader>Customer</TableHeader>
      <TableHeader>Status</TableHeader>
      <TableHeader align="end">Amount</TableHeader>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell>INV-1042</TableCell>
      <TableCell>Northwind</TableCell>
      <TableCell><Badge tone="success">Paid</Badge></TableCell>
      <TableCell align="end">1,240.00</TableCell>
    </TableRow>
    {/* … */}
  </TableBody>
</Table>
```

## Import

```tsx
import { Table, TableHead, TableBody, TableRow, TableHeader, TableCell } from "@meridui/react";
```

## Examples

### Dense, without hover

`density="sm"` tightens cells to 10px × 12px; `hoverable={false}` turns off the row hover tint for read-only tables.

```tsx
<Table density="sm" hoverable={false} scrollLabel="API keys">
  <TableHead>
    <TableRow>
      <TableHeader>Key</TableHeader>
      <TableHeader align="end">Requests</TableHeader>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell>api/search</TableCell>
      <TableCell align="end">12,480</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

### Row selection

`selected` on a row applies the accent-soft fill. Pair it with a [Checkbox](https://meridui.dev/docs/components/checkbox) column so selection is operable and announced. `scrollLabel` makes the frame a focusable, named region so keyboard users can scroll it.

```tsx
<Table scrollLabel="Invoices">
  <TableHead>
    <TableRow>
      <TableHeader><Checkbox aria-label="Select all" checked={allSelected} indeterminate={someSelected} onChange={toggleAll} /></TableHeader>
      <TableHeader>Invoice</TableHeader>
      <TableHeader align="end">Amount</TableHeader>
    </TableRow>
  </TableHead>
  <TableBody>
    {rows.map((row) => (
      <TableRow key={row.id} selected={selected.includes(row.id)}>
        <TableCell><Checkbox aria-label={"Select " + row.id} checked={selected.includes(row.id)} onChange={() => toggle(row.id)} /></TableCell>
        <TableCell>{row.id}</TableCell>
        <TableCell align="end">{row.amount}</TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>
```

### Sortable columns

Give a header `sortDirection` and `onSort`: it sets `aria-sort` on the `<th>` and wraps the label in a real button with a direction icon. Sorting the rows stays yours; use `"none"` on sortable columns that are not the active sort.

```tsx
const [sort, setSort] = useState<{ key: "name" | "amount"; dir: "ascending" | "descending" }>({ key: "name", dir: "ascending" });
const toggle = (key: "name" | "amount") =>
  setSort((s) => ({ key, dir: s.key === key && s.dir === "ascending" ? "descending" : "ascending" }));

<TableHeader sortDirection={sort.key === "name" ? sort.dir : "none"} onSort={() => toggle("name")}>
  Name
</TableHeader>
```

## API reference

Every part forwards its ref to the matching native element and passes native attributes through.

### Table

The frame `div` wraps the `<table>`; `className` and native props go on the `<table>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `density` | `"sm" \| "md"` | `"md"` | Row density: md 14px 16px cells, sm 10px 12px. |
| `hoverable` | `boolean` | `true` | Highlights rows on hover. |
| `scrollLabel` | `string` |  | Makes the scroll wrapper a focusable region with this name. Omit for tables that never overflow. |

### TableHead, TableBody

`<thead>` (on the subtle surface) and `<tbody>`. No props beyond native attributes.

### TableRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `selected` | `boolean` |  | Accent-soft fill via `data-selected`. Sets no ARIA: convey selection through the selection control (e.g. a checked checkbox cell), and pass `aria-selected` yourself only on a `role="grid"` table. |

### TableHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Text alignment; use end for numeric columns. |
| `scope` | `"col" \| "row" \| "colgroup" \| "rowgroup"` | `"col"` | Native header scope. |
| `sortDirection` | `"ascending" \| "descending" \| "none"` |  | Makes the column sortable: sets aria-sort and renders the label inside a button with a direction icon. |
| `onSort` | `(event) => void` |  | Called when the sort button is pressed. Compute the next direction and sort the rows yourself. |

### TableCell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | Text alignment; use end for numeric columns. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-table-frame` | Scrollable, hairline-ringed wrapper |
| `.mrd-table` | The <table>; `data-density` = `sm` · `md`, `data-hoverable` |
| `.mrd-table__head`, `.mrd-table__body` | Sections |
| `.mrd-table__row` | Rows; `data-selected` when selected |
| `.mrd-table__header`, `.mrd-table__cell` | Cells; `data-align` = `start` · `center` · `end` |

---

TabsBasic,
  TabsControlled,
  TabsVertical,
} from "@/examples/tabs";

# Tabs

Line tabs for switching between related panels.

```tsx
tabsBasicCode
```

## Import

```tsx
import { Tabs } from "@meridui/react";
```

## Anatomy

```tsx
<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger value="a" />
  </Tabs.List>
  <Tabs.Panel value="a" />
</Tabs.Root>
```

- **Root** holds the selected value and orientation.
- **List** is the `role="tablist"`; give it an `aria-label`.
- **Trigger** is one `role="tab"` button, linked to its panel by `value`.
- **Panel** is the `role="tabpanel"`. Inactive panels unmount unless `forceMount` is set.

## Examples

### Controlled

```tsx
tabsControlledCode
```

### Vertical

With `orientation="vertical"`, the list stacks and ArrowUp/ArrowDown move between tabs.

```tsx
tabsVerticalCode
```

## API reference

### Root

Accepts every `<div>` attribute except `defaultValue` and `onChange`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Controlled selected tab value. |
| `defaultValue` | `string` | `""` | Initially selected tab value when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called when the selected tab changes. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Arrow-key axis. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the root element. |

### List

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"line"` | `"line"` | Visual style. Only "line" today. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the tablist. |

### Trigger

Accepts every `<button>` attribute except `value`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Value identifying this tab and its panel. |
| `disabled` | `boolean` |  | Disable the tab; it is skipped by arrow keys. |
| `ref` | `Ref<HTMLButtonElement>` |  | Forwarded ref to the tab button. |

### Panel

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Value of the tab that owns this panel. |
| `forceMount` | `boolean` | `false` | Keep the panel mounted (hidden) while inactive. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref to the panel. |

## Styling

| Class | Element |
|---|---|
| `.mrd-tabs` | Root |
| `.mrd-tabs__list` | List |
| `.mrd-tabs__trigger` | Trigger |
| `.mrd-tabs__panel` | Panel |

| Attribute | On | Values |
|---|---|---|
| `data-orientation` | Root | `horizontal`, `vertical` |
| `data-variant` | List | `line` |
| `data-state` | Trigger, Panel | `active`, `inactive` |
| `data-disabled` | Trigger | present when disabled |
| `aria-selected="true"` | Trigger | the selected tab (styled with the accent underline) |

## Accessibility

Follows the WAI-ARIA [Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) with automatic activation: moving focus selects the tab. Only the selected tab is in the tab order; the panel itself is focusable so keyboard users can reach content without interactive elements.

| Keys | Action |
| --- | --- |
| `Tab` | Move focus into the tab list (selected tab), then to the panel. |
| `ArrowRight` | Horizontal: next tab, wrapping. Selects it. |
| `ArrowLeft` | Horizontal: previous tab, wrapping. Selects it. |
| `ArrowDown` | Vertical: next tab, wrapping. Selects it. |
| `ArrowUp` | Vertical: previous tab, wrapping. Selects it. |
| `Home` | First tab. |
| `End` | Last tab. |

## Guidelines

- **Do:** Use tabs for peer views of the same object, with short one- or two-word labels.
- **Don't:** Use tabs for sequential steps — use a [Stepper](https://meridui.dev/docs/components/stepper) — or for switching a small control mode, which is a [SegmentedControl](https://meridui.dev/docs/components/segmented-control).

- **Do:** Keep the tab row on one line; move rarely used views into a menu.
- **Don't:** Nest a second row of tabs inside a panel.

## Related

- [SegmentedControl](https://meridui.dev/docs/components/segmented-control)
- [Accordion](https://meridui.dev/docs/components/accordion)
- [SidebarNav](https://meridui.dev/docs/components/sidebar-nav)

---

# Text

Body text on Merid's type scale. Hierarchy comes from the three text tones and weight — not from colour and never from bold.

```tsx
<Text prose>
  Merid separates regions by surface before border, keeps one accent for
  interaction, and lets tone and weight carry hierarchy.
</Text>
```

## Import

```tsx
import { Text } from "@meridui/react";
```

## Examples

### Sizes

`lg` is the 18px lead, `md` the 16px body (default), stepping down to the 12px `3xs` caption.

```tsx
<Text size="lg">lg: lead paragraph, 18px</Text>
<Text size="md">md: body, 16px</Text>
<Text size="sm">sm: secondary text</Text>
<Text size="xs">xs: dense UI text</Text>
<Text size="2xs">2xs: meta</Text>
<Text size="3xs">3xs: caption, 12px</Text>
```

### Tones

`ink`, `body` (default) and `muted` are the hierarchy tones. `accent` and `danger` are for the rare text that must carry meaning through colour.

```tsx
<Text tone="ink">ink: headings and strong text</Text>
<Text tone="body">body: default running text</Text>
<Text tone="muted">muted: meta only</Text>
<Text tone="accent">accent: interactive emphasis</Text>
<Text tone="danger">danger: error copy</Text>
```

### Weights

```tsx
<Text weight="regular">Regular</Text>
<Text weight="medium">Medium</Text>
<Text weight="semibold">Semibold</Text>
```

### Numbers and other elements

`numeric` turns on tabular numerals so figures line up. `as` renders another element — `span` inside a line, `small`, `div`.

```tsx
<Text numeric>1,204.50</Text>
<Text numeric>987.10</Text>
<Text as="span" size="sm" tone="muted">Rendered as a span</Text>
```

## API reference

`Text` renders a `<p>` by default, forwards its ref and passes other HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"lg" \| "md" \| "sm" \| "xs" \| "2xs" \| "3xs"` | `"md"` | Type scale step: lg 18px lead down to 3xs 12px caption. |
| `tone` | `"ink" \| "body" \| "muted" \| "accent" \| "danger"` | `"body"` | Text tone. |
| `weight` | `"regular" \| "medium" \| "semibold"` | `"regular"` | Font weight. There is no bold. |
| `numeric` | `boolean` | `false` | Uses tabular numerals. |
| `prose` | `boolean` | `false` | Caps the line length at the 720px reading width. |
| `as` | `ElementType` | `"p"` | Element or component to render instead. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-text` | Root element |
| `data-size` | `lg` · `md` · `sm` · `xs` · `2xs` · `3xs` |
| `data-tone` | `ink` · `body` · `muted` · `accent` · `danger` |
| `data-weight` | `regular` · `medium` · `semibold` |
| `data-numeric` | Present when `numeric` |
| `data-prose` | Present when `prose` |

There are no text-specific variables; sizes and tones read the global typography and colour tokens.

## Accessibility

- `muted` falls below 4.5:1 on the page background in light mode. Use it for meta text only, never for content a reader must understand.
- Do not convey meaning through `accent` or `danger` colour alone — pair it with wording or an icon.

## Guidelines

- **Do:** Build hierarchy with `ink` / `body` / `muted` and `medium` weight.
- **Don't:** Colour text blue for emphasis, or reach for a heavier weight than semibold.

## Related

- [Heading](https://meridui.dev/docs/components/heading) — titles and section headings.
- [Code](https://meridui.dev/docs/components/code) and [Kbd](https://meridui.dev/docs/components/kbd) — inline technical text.

---

# Textarea

A multi-line text input for comments, descriptions and messages. Inside a [Field](https://meridui.dev/docs/components/field) it picks up its id, description, error and required state.

```tsx
<Textarea aria-label="Message" placeholder="Write a message…" />
```

## Import

```tsx
import { Textarea } from "@meridui/react";
```

## Examples

### Resize

The handle defaults to `vertical`. Use `none` when the layout must not change, `both` rarely.

```tsx
<Textarea rows={2} placeholder="resize vertical (default)" />
<Textarea rows={2} resize="none" placeholder="resize none" />
<Textarea rows={2} resize="both" placeholder="resize both" />
```

### Invalid and disabled

```tsx
<Textarea rows={2} invalid defaultValue="Too short" />
<Textarea rows={2} disabled defaultValue="Disabled" />
```

### Controlled with a counter

```tsx
const [value, setValue] = useState("");

<Textarea
  aria-label="Status"
  value={value}
  maxLength={140}
  onChange={(event) => setValue(event.target.value)}
/>
<Text size="xs" tone="muted" numeric>{value.length} / 140</Text>
```

## API reference

`Textarea` forwards its ref to the `<textarea>` and passes every other native attribute through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `resize` | `"none" \| "vertical" \| "both"` | `"vertical"` | User resize handle. |
| `invalid` | `boolean` |  | Forces the invalid style (`data-invalid`) and `aria-invalid`. Inside a Field, derived from its error. |
| `rows` | `number` | `4` | Visible text lines (native). |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-textarea` | The <textarea> |
| `data-resize` | `none` · `vertical` · `both` |
| `data-invalid` | Present when invalid; drives the danger border (`aria-invalid` carries the semantics) |

Textarea shares the Input styles in `input.css`; it has no size variants.

## Accessibility

- Give it a visible label through [Field](https://meridui.dev/docs/components/field) or [Label](https://meridui.dev/docs/components/label).
- If you show a character counter, keep `maxLength` and the visible count in sync; consider linking the counter with `aria-describedby`.

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus to the textarea. |
| `Enter` | Inserts a line break (it does not submit the form). |

## Guidelines

- **Do:** Size `rows` to the expected answer length so people know how much to write.
- **Don't:** Use a Textarea for single-line values like names or emails.

## Related

- [Input](https://meridui.dev/docs/components/input) — single-line text.
- [Field](https://meridui.dev/docs/components/field) — label, description and error wiring.

---

ToastBasic,
  ToastTones,
  ToastAction,
} from "@/examples/toast";

# Toast

Brief, non-blocking notifications stacked in the corner of the screen.

```tsx
toastBasicCode
```

## Import

```tsx
import { ToastProvider, useToast } from "@meridui/react";
```

## Anatomy

Toasts are imperative. Wrap the app once in `ToastProvider`, then call `toast()` from `useToast` anywhere below it.

```tsx
<ToastProvider>
  <App /> {/* const { toast, dismiss } = useToast(); */}
</ToastProvider>
```

Each toast renders a status dot, a title, an optional description, an optional action button and a dismiss button. The provider portals a labelled region with a polite live list to the bottom-right of the viewport.

## Examples

### Tones

The tone only changes the status dot colour.

```tsx
toastTonesCode
```

### Action, persistence and dismiss

`duration: Infinity` keeps a toast until it is dismissed. Choosing the action runs `onClick` and dismisses the toast. Reusing an `id` replaces the existing toast instead of stacking a new one.

```tsx
toastActionCode
```

## API reference

### ToastProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | App content. |
| `duration` | `number` | `5000` | Default auto-dismiss delay in ms. |
| `limit` | `number` | `3` | Maximum toasts visible at once; oldest are dropped. |
| `label` | `string` | `"Notifications"` | Accessible name of the notification region. |
| `dismissLabel` | `string` | `"Dismiss notification"` | Accessible name of each toast's close button. Translate it for other languages. |

### useToast()

Returns `ToastApi`. Throws when called outside `ToastProvider`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `toast` | `(options: ToastOptions) => string` |  | Shows a toast and returns its id. |
| `dismiss` | `(id?: string) => void` |  | Removes a toast by id, or all toasts when omitted. |

### ToastOptions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  | Short headline. |
| `description` | `ReactNode` |  | Optional supporting text. |
| `tone` | `"neutral" \| "info" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status dot colour. |
| `duration` | `number` | `provider duration` | Auto-dismiss after this many ms; Infinity keeps it until closed. |
| `action` | `{ label: string; onClick: () => void }` |  | Optional action button. |
| `id` | `string` |  | Reuse an id to replace an existing toast; its timer restarts with the new `duration`. |

## Styling

| Class | Element |
|---|---|
| `.mrd-toast-region`, `.mrd-toast-region__list` | Region and live list |
| `.mrd-toast` | One toast |
| `.mrd-toast__dot` | Status dot |
| `.mrd-toast__body`, `.mrd-toast__title`, `.mrd-toast__description` | Text |
| `.mrd-toast__action` | Action button |
| `.mrd-toast__close` | Dismiss button |

| Attribute | On | Values |
|---|---|---|
| `data-tone` | `.mrd-toast` | `neutral`, `info`, `success`, `warning`, `danger` |

## Accessibility

Toasts follow the WAI-ARIA [alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) in its polite form: the list is an `aria-live="polite"` region inside a labelled `<section>`, so new toasts are announced without interrupting. The auto-dismiss timer pauses while the pointer is over a toast or focus is inside it.

| Keys | Action |
| --- | --- |
| `Tab` | Reach the action and dismiss buttons of visible toasts. |
| `Enter` | Activate the focused action or dismiss button. |
| `Space` | Activate the focused action or dismiss button. |

> Toasts disappear. Never put the only path to a critical action or an error that blocks progress in a toast — use an [Alert](https://meridui.dev/docs/components/alert) or [AlertDialog](https://meridui.dev/docs/components/alert-dialog).

## Guidelines

- **Do:** Confirm an action the person just took, in a few words: “Changes saved”.
- **Don't:** Show a toast for something the person can already see change on screen.

- **Do:** Offer Undo on reversible destructive actions and keep that toast until dismissed.
- **Don't:** Stack several toasts for one event, or use long descriptions.

## Related

- [Alert](https://meridui.dev/docs/components/alert) — persistent inline notice.
- [AlertDialog](https://meridui.dev/docs/components/alert-dialog) — blocking confirmation.

---

# ToggleGroup

Two-state buttons (`aria-pressed`). Use `Toggle` for one option that stays on, and `ToggleGroup` for a set: `type="single"` is a deselectable choice, `type="multiple"` independent toggles.

```tsx
const [align, setAlign] = useState("left");

<ToggleGroup type="single" aria-label="Text alignment" value={align} onValueChange={setAlign}>
  <ToggleGroupItem value="left" aria-label="Align left"><AlignLeftIcon /></ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center"><AlignCenterIcon /></ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right"><AlignRightIcon /></ToggleGroupItem>
</ToggleGroup>
```

## Import

```tsx
import { Toggle, ToggleGroup, ToggleGroupItem } from "@meridui/react";
```

## Examples

### Multiple

```tsx
const [format, setFormat] = useState<string[]>(["bold"]);

<ToggleGroup type="multiple" aria-label="Formatting" value={format} onValueChange={setFormat}>
  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
  <ToggleGroupItem value="underline">Underline</ToggleGroupItem>
</ToggleGroup>
```

### Toggle

```tsx
<Toggle defaultPressed>Show grid</Toggle>
<Toggle size="sm">Snap</Toggle>
<Toggle disabled>Rulers</Toggle>
```

## API reference

### Toggle

Accepts every `<button>` attribute; the ref goes to the button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pressed` | `boolean` |  | Controlled pressed state. |
| `defaultPressed` | `boolean` | `false` | Initial state when uncontrolled. |
| `onPressedChange` | `(pressed: boolean) => void` |  | Called with the new state. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height. |

### ToggleGroup

Renders a `div role="group"`; name it with `aria-label` or `aria-labelledby`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"single" \| "multiple"` |  | One item on at a time (pressing it again turns it off), or any number. |
| `value` | `string \| string[]` |  | Controlled value: string ("" for none) or string[]. |
| `defaultValue` | `string \| string[]` |  | Initial value when uncontrolled. |
| `onValueChange` | `(value) => void` |  | Called with the new value. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Which arrow keys move focus, and the layout. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of every item. |
| `disabled` | `boolean` | `false` | Disables every item. |

### ToggleGroupItem

Accepts every `<button>` attribute except `value`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Value reported when this item is on. |
| `disabled` | `boolean` |  | Disables the item; arrow keys skip it. |

## Styling

| Class | Element |
|---|---|
| `.mrd-toggle` | Toggle and every group item (`data-state="on" \| "off"`, `data-size`) |
| `.mrd-toggle-group` | Group (`data-orientation`) |
| `.mrd-toggle-group__item` | Group item |

## Accessibility

Every item is a `<button aria-pressed>`, so screen readers announce "pressed" / "not pressed". The group is one tab stop (roving `tabindex`); arrow keys move focus without changing the state, Space or Enter toggles. Icon-only items need an `aria-label`.

| Keys | Action |
| --- | --- |
| `Tab` | Move into the group (to the pressed item or the first) and out of it. |
| `ArrowRight` `ArrowDown` | Next item (wraps; ArrowLeft in RTL). |
| `ArrowLeft` `ArrowUp` | Previous item (wraps). |
| `Home` `End` | First / last item. |
| `Space` `Enter` | Toggle the focused item. |

## Guidelines

- **Do:** Use a single ToggleGroup for tool options that apply immediately, like text alignment.
- **Don't:** Use it to switch between views or pages; that is [SegmentedControl](https://meridui.dev/docs/components/segmented-control) or [Tabs](https://meridui.dev/docs/components/tabs).

## Related

- [SegmentedControl](https://meridui.dev/docs/components/segmented-control) — one required choice between views.
- [Switch](https://meridui.dev/docs/components/switch) — a setting that is on or off.

---

# Toolbar

A row of related controls (formatting buttons, view options, a menu) that is a single Tab stop; the arrow keys move between its controls.

```tsx
toolbarBasicCode
```

## Import

```tsx
import { Toolbar } from "@meridui/react";
```

## Anatomy

```tsx
<Toolbar.Root aria-label="…">
  <Toolbar.Group aria-label="…">
    <Toolbar.Button />
  </Toolbar.Group>
  <Toolbar.Separator />
  <Toolbar.Link />
</Toolbar.Root>
```

- **Root** is the `role="toolbar"` element. Give it an `aria-label`.
- **Button** and **Link** are the items the arrow keys move between. With `asChild` any element joins, e.g. a `DropdownMenu.Trigger`.
- **Group** (`role="group"`) and **Separator** organise the items.

## Examples

### Toggle buttons

A formatting toggle is a Toolbar.Button with `aria-pressed`; the pressed state gets the accent-soft fill. For a set where only one can be on, keep the state in your component.

### Menus in a toolbar

Wrap a Toolbar.Button in `DropdownMenu.Trigger asChild`, as in the example above. The menu opens with Enter, Space or ArrowDown; closing it returns focus to the toolbar.

## API reference

### Root

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Accessible name; required unless you pass aria-labelledby. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout and arrow-key axis. |
| `loop` | `boolean` | `true` | Wrap from the last item to the first. |
| `ref` | `Ref<HTMLDivElement>` |  | Forwarded ref. |

### Button

Accepts every `<button>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Sets aria-disabled and blocks clicks; skipped by the arrow keys. |
| `asChild` | `boolean` | `false` | Render the single child element instead of a <button>. |
| `ref` | `Ref<HTMLButtonElement>` |  | Forwarded ref. |

### Link, Group, Separator

Link accepts every `<a>` attribute and `asChild`. Group and Separator accept every `<div>` attribute; the separator's `aria-orientation` is set perpendicular to the toolbar.

## Styling

| Class | Element |
|---|---|
| `.mrd-toolbar` | Root |
| `.mrd-toolbar__group` | Group |
| `.mrd-toolbar__button`, `.mrd-toolbar__link` | Button and Link (unless `asChild`) |
| `.mrd-toolbar__separator` | Separator |

| Attribute | On | Values |
|---|---|---|
| `data-orientation` | Root | `horizontal`, `vertical` |
| `aria-pressed` | Button | `true` gets the pressed style |
| `data-disabled` | Button | present when disabled |

## Accessibility

Follows the WAI-ARIA [Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) with a roving tabindex: only one item is in the Tab sequence, and the toolbar remembers the last focused item. Right and Left follow reading direction in RTL.

| Keys | Action |
| --- | --- |
| `Tab` | Move into the toolbar (to the last focused item) or out of it. |
| `ArrowRight` | Next item, wrapping (ArrowDown when vertical). |
| `ArrowLeft` | Previous item, wrapping (ArrowUp when vertical). |
| `Home` | First item. |
| `End` | Last item. |
| `Enter` `Space` | Activate the focused button. |

## Guidelines

- **Do:** Group three or more related controls that act on the same thing, like the text in an editor.
- **Don't:** Wrap a page's unrelated buttons in a toolbar just for the look; each would lose its own Tab stop.

## Related

- [DropdownMenu](https://meridui.dev/docs/components/dropdown-menu): menus inside a toolbar.
- [SegmentedControl](https://meridui.dev/docs/components/segmented-control): switch between a few views.

---

# Tooltip

A short label that appears on hover after a delay and immediately on focus.

## Import

```tsx
import { Tooltip } from "@meridui/react";
```

```tsx
<Tooltip content="Copies the link to your clipboard">
  <IconButton label="Copy link" icon={<CopyIcon />} variant="secondary" />
</Tooltip>
```

## Anatomy

Tooltip is a single component. Its child must be one focusable element that forwards its ref, such as `Button` or `IconButton`. The tooltip adds `aria-describedby` and pointer and focus handlers to that element.

```tsx
<Tooltip content="…">
  <Button />
</Tooltip>
```

## Examples

### Placement

```tsx
<Tooltip content="On the top" placement="top"><Button variant="secondary" size="sm">top</Button></Tooltip>
<Tooltip content="On the right" placement="right"><Button variant="secondary" size="sm">right</Button></Tooltip>
<Tooltip content="On the bottom" placement="bottom"><Button variant="secondary" size="sm">bottom</Button></Tooltip>
<Tooltip content="On the left" placement="left"><Button variant="secondary" size="sm">left</Button></Tooltip>
```

### Delay and disabled

```tsx
<Tooltip content="Saved" delay={0}>…</Tooltip>
<Tooltip content="Unavailable offline" disabled={isOnline}>…</Tooltip>
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `ReactNode` |  | Tooltip text. Keep it short and non-interactive. |
| `children` | `ReactElement` |  | A single focusable element (e.g. an icon Button). Receives aria-describedby. |
| `open` | `boolean` |  | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` |  | Called when the open state should change. |
| `delay` | `number` | `400` | Hover delay before opening, in ms. Focus opens immediately. |
| `placement` | `Placement` | `"top"` | Preferred placement. |
| `sideOffset` | `number` | `6` | Distance from the trigger in px. |
| `className` | `string` |  | Class name for the tooltip bubble. |
| `disabled` | `boolean` | `false` | Do not show the tooltip. |
| `container` | `Element \| null` | `document.body` | Portal target. `undefined` uses `document.body`; `null` renders nothing until the target exists. |

## Styling

`.mrd-tooltip` is the bubble: `--mrd-tooltip-bg` / `--mrd-tooltip-fg`, `--mrd-radius-sm`, `--mrd-shadow-lg`, 280px max width, `z-index: var(--mrd-z-tooltip)`. It carries `data-state="open"` and `pointer-events: none`.

## Accessibility

Follows the [WAI-ARIA Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/). The bubble has `role="tooltip"` and is linked to the trigger with `aria-describedby` while open. Touch pointers do not open it, so never put essential information only in a tooltip. An icon-only trigger still needs its own accessible name (`IconButton`'s `label`).

| Keys | Action |
| --- | --- |
| `Tab` | Focusing the trigger shows the tooltip immediately; moving focus away hides it. |
| `Esc` | Hides the tooltip. |

## Guidelines

- **Do:** Use a tooltip to name an icon-only control or add a brief hint.
- **Don't:** Put links, buttons or long text in a tooltip; use a Popover.

## Related

- [Popover](https://meridui.dev/docs/components/popover) for interactive content.
- [IconButton](https://meridui.dev/docs/components/icon-button)

---

# VisuallyHidden

Hides content from sight while keeping it in the accessibility tree. Use it for context that is obvious visually but not when read aloud.

```tsx
<Text>
  Revenue up 12%
  <VisuallyHidden> compared with last month</VisuallyHidden>
</Text>
```

## Import

```tsx
import { VisuallyHidden } from "@meridui/react";
```

## Examples

### Hidden heading

A region that is obvious from layout still benefits from a heading for screen-reader navigation. `as` renders the right element.

```tsx
<nav aria-labelledby="vh-nav">
  <VisuallyHidden as="h2" id="vh-nav">Account settings</VisuallyHidden>
  <IconButton label="Settings" icon={<SettingsIcon />} />
</nav>
```

## API reference

Renders a `<span>` by default, forwards its ref and passes other HTML attributes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `ElementType` | `"span"` | Element or component to render instead. |

## Styling

| Hook | Values |
| --- | --- |
| `.mrd-visually-hidden` | The clip pattern; usable on any element without the component |

## Accessibility

- Content stays readable by screen readers and in the tab order if focusable. Do not hide focusable elements — a sighted keyboard user would focus something invisible.
- For icon-only buttons, prefer [IconButton](https://meridui.dev/docs/components/icon-button)'s `label`, which sets `aria-label` directly.

## Guidelines

- **Do:** Add short context that the visual layout already implies, like “compared with last month”.
- **Don't:** Hide keyword-stuffed text or content that sighted users also need.

## Related

- [IconButton](https://meridui.dev/docs/components/icon-button) — names icon-only actions.
- [Link](https://meridui.dev/docs/components/link) — uses the same class for its “opens in a new tab” hint.

---

# React Hook Form

Merid's form controls are thin wrappers over native elements, so most of them work with [React Hook Form](https://react-hook-form.com)'s `register` unchanged. The three controls that hold their own state — `Select`, `RadioGroup` and `Switch` — go through `Controller`.

```tsx
const { register, control, handleSubmit, formState: { errors, isSubmitting } } =
  useForm<InviteValues>({ defaultValues: DEFAULTS, mode: "onTouched" });

<form onSubmit={handleSubmit(onSubmit)} noValidate>
  <Field label="Email" required error={errors.email?.message}>
    <Input type="email" {...register("email", { required: "Enter an email address." })} />
  </Field>
  <Controller control={control} name="region" rules={{ required: "Pick a data region." }}
    render={({ field, fieldState }) => (
      <Field id="rhf-region" label="Data region" required error={fieldState.error?.message}>
        <Select.Root value={field.value} onValueChange={field.onChange} name={field.name}>
          <Select.Trigger id="rhf-region" ref={field.ref} invalid={fieldState.invalid} />
          <Select.Content>…</Select.Content>
        </Select.Root>
      </Field>
    )} />
  <Button type="submit" variant="primary" loading={isSubmitting}>Send invite</Button>
</form>
```

## Which API for which control

| Control | Use | Why |
|---|---|---|
| `Input`, `Textarea`, `NativeSelect` | `register` | They forward `ref`, `name`, `onChange` and `onBlur` to the native element. |
| `Checkbox` | `register` | Renders a real `<input type="checkbox">`; the value is a boolean. |
| `Select` | `Controller` | A custom listbox. It takes `value` / `onValueChange`, not a change event. |
| `RadioGroup` + `Radio` | `Controller` | The group owns the selected value and roving focus. |
| `Switch` | `Controller` | A `<button role="switch">`; takes `checked` / `onCheckedChange`. |
| `SegmentedControl` | `Controller` | Same as `Select`: `value` / `onValueChange`. |

## Errors

Pass the message to `Field`'s `error` prop. Field then sets `aria-invalid="true"` on the control, adds the message to its `aria-describedby`, and shows the invalid style. When `error` is `undefined` the wiring is removed again, so no extra state is needed.

```tsx
<Field label="Email" required error={errors.email?.message}>
  <Input type="email" {...register("email", { required: "Enter an email address." })} />
</Field>
```

`Checkbox` has no Field wrapper of its own label, so pass `invalid` and render the message yourself (as in the example above).

## Select inside Field

`Select.Trigger` does not read Field's context yet, so give both the same `id`: the Field label then points at the trigger, and pass `invalid` from `fieldState`. Call `field.onBlur` when the listbox closes so `mode: "onTouched"` validates at the right time.

```tsx
<Field id="plan" label="Plan" error={fieldState.error?.message}>
  <Select.Root value={field.value} onValueChange={field.onChange}
    onOpenChange={(open) => { if (!open) field.onBlur(); }}>
    <Select.Trigger id="plan" ref={field.ref} invalid={fieldState.invalid} />
    <Select.Content>…</Select.Content>
  </Select.Root>
</Field>
```

Passing `ref={field.ref}` lets React Hook Form focus the trigger when validation fails on submit.

## Submit state

Use `formState.isSubmitting` for the button's `loading` prop. A loading Button keeps its width, shows a spinner, sets `aria-busy` and ignores clicks, so a second submit cannot be fired while the first is in flight.

## Schema validation

To validate with a schema instead of `rules`, see [Validation with Zod](https://meridui.dev/docs/integrations/zod).

---

# Validation with Zod

Merid does not validate anything itself. `Field` only renders the message you give it, so any validator works. This page shows [Zod](https://zod.dev) in the two common setups. The code is not previewed live because this site does not depend on Zod; the [React Hook Form](https://meridui.dev/docs/integrations/react-hook-form) page has a live form with the same wiring.

## With React Hook Form

```bash
npm i zod @hookform/resolvers react-hook-form
```

```tsx
"use client";

import { zodResolver } from "@hookform/resolvers/zod";
import { Controller, useForm } from "react-hook-form";
import { z } from "zod";
import { Button, Field, Input, Select, Stack, Switch } from "@meridui/react";

const schema = z.object({
  name: z.string().trim().min(2, "Use at least 2 characters."),
  email: z.email("Enter a valid email address."),
  plan: z.enum(["starter", "team"], { error: "Pick a plan." }),
  marketing: z.boolean(),
});
type Values = z.infer<typeof schema>;

export function SignupForm() {
  const { register, control, handleSubmit, formState: { errors, isSubmitting } } = useForm<Values>({
    resolver: zodResolver(schema),
    defaultValues: { name: "", email: "", marketing: false },
  });

return (
    <form onSubmit={handleSubmit(async (values) => { await save(values); })} noValidate>
      <Stack gap={5}>
        <Field label="Name" required error={errors.name?.message}>
          <Input {...register("name")} autoComplete="name" />
        </Field>
        <Field label="Email" required error={errors.email?.message}>
          <Input type="email" {...register("email")} autoComplete="email" />
        </Field>
        <Controller control={control} name="plan" render={({ field, fieldState }) => (
          <Field id="plan" label="Plan" required error={fieldState.error?.message}>
            <Select.Root value={field.value ?? ""} onValueChange={field.onChange} placeholder="Choose a plan">
              <Select.Trigger id="plan" ref={field.ref} invalid={fieldState.invalid} />
              <Select.Content>
                <Select.Item value="starter">Starter</Select.Item>
                <Select.Item value="team">Team</Select.Item>
              </Select.Content>
            </Select.Root>
          </Field>
        )} />
        <Controller control={control} name="marketing" render={({ field }) => (
          <Switch checked={field.value} onCheckedChange={field.onChange}>Product updates</Switch>
        )} />
        <Button type="submit" variant="primary" loading={isSubmitting}>Create account</Button>
      </Stack>
    </form>
  );
}
```

Zod messages go straight into `Field`'s `error`, which sets `aria-invalid` and `aria-describedby` on the control.

## Without a form library

For small forms, parse `FormData` with `safeParse` and keep the flattened errors in state.

```tsx
const [errors, setErrors] = useState<Partial<Record<keyof Values, string>>>({});

## Next.js server actions

Validate again on the server — client validation is a convenience, not a guarantee. Return the field errors from the action and render them with `useActionState`.

```tsx
// app/signup/actions.ts
"use server";
export async function signup(_prev: State, formData: FormData): Promise<State> {
  const result = schema.safeParse(Object.fromEntries(formData));
  if (!result.success) return { errors: z.flattenError(result.error).fieldErrors };
  await createUser(result.data);
  return { errors: {} };
}
```

```tsx
// app/signup/form.tsx
"use client";
const [state, action, pending] = useActionState(signup, { errors: {} });

<form action={action}>
  <Field label="Email" error={state.errors.email?.[0]}>
    <Input name="email" type="email" />
  </Field>
  <Button type="submit" variant="primary" loading={pending}>Create account</Button>
</form>
```

`Switch` submits through a hidden input only when it is on and has a `name`, like a native checkbox. Use `z.coerce.boolean()` or `formData.has("marketing")` on the server.

---

# Next.js

Merid works in the App Router without configuration. This site is itself a Next.js 16 app built with it.

```bash
npx create-next-app@latest my-app
cd my-app
npx @meridui/cli init
```

`init` installs `@meridui/react`, imports the stylesheet in `app/layout.tsx` and fixes the template's `globals.css` (see [below](#the-templates-globals-css)). Every change is shown as a diff before it is written.

## Set up

```tsx
// app/layout.tsx
import type { Metadata, Viewport } from "next";
import "@meridui/react/styles.css";
import "./globals.css"; // your CSS after Merid's (with Tailwind, the other way round; see below)

export const metadata: Metadata = {
  title: { default: "Acme", template: "%s — Acme" },
};

export const viewport: Viewport = {
  // Matches --mrd-bg in light and dark so mobile browser chrome blends in.
  themeColor: [
    { media: "(prefers-color-scheme: light)", color: "#ffffff" },
    { media: "(prefers-color-scheme: dark)", color: "#0b0d12" },
  ],
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

The base layer applies typography, background and focus styles to the document at zero specificity; no class is needed. No `transpilePackages` entry is needed. In server component files use the flat part names (`DialogRoot`, `TabsList`, …) and `asChild` for router links; see [Server components](https://meridui.dev/docs/server-components).

## The template's globals.css

`create-next-app` writes an `app/globals.css` whose rules are not in a cascade layer, so they beat Merid's.

With Tailwind (the default), two things need changing. The `body` rule sets Arial and the template's colours; remove it. And Tailwind's reset, Preflight, is in a layer named `base`: when Merid's stylesheet loads first, that layer ends up above Merid's and strips the padding, borders and background from buttons and inputs. Put the layer order at the top of `globals.css` and import `globals.css` before Merid:

```css
/* app/globals.css */
@layer theme, base, merid, components, utilities;

@import "tailwindcss";
```

```tsx
// app/layout.tsx
import "./globals.css";
import "@meridui/react/styles.css";
```

Without Tailwind, the template adds `* { padding: 0; margin: 0 }`, which takes the padding off every component, `a { color: inherit; text-decoration: none }`, which hides `Link`, and Arial on `body`. Remove those and keep `body { margin: 0 }`. The `--background` and `--foreground` variables can stay; Merid does not use them.

`npx @meridui/cli init` makes these changes and asks before writing. It only removes rules that still match the template, so your own edits stay. `npx @meridui/cli doctor` warns while any of them are left. See [Tailwind CSS](https://meridui.dev/docs/integrations/tailwind) for mapping Merid's tokens into your Tailwind theme.

## Server components

Every interactive component ships its own `"use client"` directive, so you can import from `@meridui/react` in a server component and render it directly. Presentational components (`Card`, `Stack`, `Heading`, `Text`, `Badge`, `Table`, …) render on the server with no client JavaScript of their own. Event handlers still need a client boundary — see [Server components](https://meridui.dev/docs/server-components).

```tsx
// app/projects/page.tsx — a server component
import { Badge, Card, Heading, Stack, Text } from "@meridui/react";

export default async function Projects() {
  const projects = await db.project.findMany();
  return (
    <Stack gap={4}>
      <Heading level={1} size="h2">Projects</Heading>
      {projects.map((p) => (
        <Card key={p.id} variant="outline">
          <Text tone="ink" weight="medium">{p.name}</Text>
          <Badge tone={p.live ? "success" : "neutral"}>{p.live ? "Live" : "Draft"}</Badge>
        </Card>
      ))}
    </Stack>
  );
}
```

## Links

Components that render an anchor take an `as` prop, so `next/link` gives them client-side navigation and prefetching:

```tsx
import NextLink from "next/link";
import { Breadcrumb, Card, SidebarNav } from "@meridui/react";

<SidebarNav.Item as={NextLink} href="/settings" active={pathname === "/settings"}>Settings</SidebarNav.Item>
<Breadcrumb.Link as={NextLink} href="/projects">Projects</Breadcrumb.Link>
<Card as={NextLink} href={`/projects/${id}`} interactive>…</Card>
```

Overlay triggers (`Dialog.Trigger`, `Popover.Trigger`, `DropdownMenu.Trigger`, `Tooltip`) take `asChild`, so a `next/link` can also be a tooltip or menu anchor.

`Button`, `Link` and `Breadcrumb.Link` take `asChild`, which also works in server component files where `as={NextLink}` cannot be passed:

```tsx
<Button asChild variant="primary">
  <NextLink href="/new">New project</NextLink>
</Button>

<Link asChild>
  <NextLink href="/pricing">Pricing</NextLink>
</Link>
```

`Pagination` with `getHref` renders plain anchors (full page loads). Pass `renderLink` to route them through `next/link`: `renderLink={({ page, ...props }) => <NextLink {...props} />}`. Or use `onPageChange` and `router.push` in an app, and keep `getHref` for crawlable pagination on public pages.

## Fonts

Merid bundles Geist and Geist Mono and loads them through `@font-face` in its stylesheet, so nothing else is needed. To use `next/font` instead (self-hosted, preloaded, no layout shift), point the tokens at its variable:

```tsx
import { Inter } from "next/font/google";
const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });

<html lang="en" className={inter.variable}>
```

```css
/* globals.css */
:root {
  --mrd-font-sans: var(--font-inter), ui-sans-serif, system-ui, sans-serif;
}
```

Browsers only download faces that are used, so the bundled Geist files are never requested once the token points elsewhere.

## Dark mode without a flash

Set `data-theme` before first paint with an inline script in `<head>`, and add `suppressHydrationWarning` to `<html>` because the attribute differs from the server render. See [Dark mode strategies](https://meridui.dev/docs/integrations/dark-mode).

---

# React Router and TanStack Router

Merid's navigation parts render an `<a>` by default and accept an `as` prop for a router's link component. The router then handles the click, and Merid keeps the classes, `aria-current` and focus styles.

| Component | Router prop | Notes |
|---|---|---|
| `SidebarNav.Item` | `as` | Pass `active` yourself; it sets `aria-current="page"`. |
| `Breadcrumb.Link` | `as` | The last crumb is `Breadcrumb.Page`, not a link. |
| `Card` | `as` | Use with `interactive` for a clickable card. |
| `Button`, `Link` | — | No `as` yet: put the classes on the router link (below). |

## React Router

```tsx
import { Link as RouterLink, NavLink, useLocation } from "react-router";
import { Breadcrumb, SidebarNav } from "@meridui/react";

function AppNav() {
  const { pathname } = useLocation();
  return (
    <SidebarNav aria-label="Main">
      <SidebarNav.Item as={RouterLink} to="/" href="/" active={pathname === "/"}>Overview</SidebarNav.Item>
      <SidebarNav.Item as={RouterLink} to="/settings" href="/settings" active={pathname.startsWith("/settings")}>
        Settings
      </SidebarNav.Item>
    </SidebarNav>
  );
}

<Breadcrumb.Link as={RouterLink} to="/projects">Projects</Breadcrumb.Link>
```

React Router's `Link` takes `to`; passing `href` as well keeps TypeScript happy with Merid's anchor props and is ignored by the router. Avoid `NavLink` here: its `className` function signature conflicts with Merid's string class. Compute `active` from `useLocation` or `useMatch` instead.

## TanStack Router

```tsx
import { Link, useMatchRoute } from "@tanstack/react-router";
import { SidebarNav } from "@meridui/react";

function AppNav() {
  const matchRoute = useMatchRoute();
  return (
    <SidebarNav aria-label="Main">
      <SidebarNav.Item as={Link} to="/projects" active={Boolean(matchRoute({ to: "/projects", fuzzy: true }))}>
        Projects
      </SidebarNav.Item>
    </SidebarNav>
  );
}
```

TanStack's `Link` renders an `<a href>` itself, so `to` is enough. Its typed route checking does not flow through `as`; if you want it, wrap the link once:

```tsx
import { createLink } from "@tanstack/react-router";
import { SidebarNavItem } from "@meridui/react";

export const NavItem = createLink(SidebarNavItem);
// <NavItem to="/projects/$id" params={{ id }} active={…}>Northwind</NavItem>
```

## Buttons that navigate

`Button` renders a `<button>`. For navigation, use a link with Merid's button classes so middle-click, "open in new tab" and prefetching keep working:

```tsx
<RouterLink to="/projects/new" className="mrd-button" data-variant="primary" data-size="md">
  <span className="mrd-button__content">New project</span>
</RouterLink>
```

## Pagination

`Pagination` takes `onPageChange`; drive it from the URL:

```tsx
const [params, setParams] = useSearchParams();
const page = Number(params.get("page") ?? 1);

<Pagination pageCount={20} page={page} onPageChange={(p) => setParams({ page: String(p) })} />
```

---

# Vite

```bash
npm create vite@latest my-app -- --template react-ts
cd my-app
npx @meridui/cli init
```

`init` installs `@meridui/react`, adds the stylesheet import below and removes the template styles that would override Merid (next section). It shows every change as a diff and asks first. To set up by hand, run `npm i @meridui/react` and follow the rest of this page.

## Entry file

Import Merid's stylesheet before your own CSS.

```tsx
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "@meridui/react/styles.css";
import "./index.css";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);
```

The base layer styles the document itself; `mrd-root` is only needed to re-apply it to a subtree inside a host page with other styles.

## The template's index.css

The Vite template's `src/index.css` is written for its starter page. It sets the page font, size and colours on `:root`, sizes `h1` and `h2`, styles `code`, sets `p { margin: 0 }` and turns `#root` into a centred 1126px column with centred text. Templates before create-vite 9 also style every `button` and `a`, and centre `body` with flexbox. These rules are not in a cascade layer, so they beat Merid's (see [Styling and CSS layers](https://meridui.dev/docs/styling)): headings take the template's sizes, and with the older template a primary button gets a grey background.

`npx @meridui/cli init` removes them and leaves `body { margin: 0 }`, which is what most apps want:

```css
/* src/index.css after init */
body {
  margin: 0;
}
```

It only removes rules that still match the template, so anything you have edited or added stays. `App.css` is left alone unless it has the older template's `#root` rule; the rest of it only styles the starter page's own classes. To clean up by hand, delete the same rules. `npx @meridui/cli doctor` warns while any of them are left.

## Fonts

Vite resolves the `url("../fonts/…")` in Merid's CSS from `node_modules` and copies the two `.woff2` files into `dist/assets` with hashed names. Nothing to configure. To use your own font instead, set `--mrd-font-sans` in your CSS; the bundled face is then never requested.

## Dark mode before paint

Add a small inline script to `index.html` so the page never flashes the wrong theme:

```html
<script>
  try {
    const t = localStorage.getItem("theme");
    if (t === "light" || t === "dark") document.documentElement.dataset.theme = t;
  } catch {}
</script>
```

See [Dark mode strategies](https://meridui.dev/docs/integrations/dark-mode) for the toggle.

## Library mode

If you build your own component package on top of Merid with Vite's library mode, list `@meridui/react`, `react` and `react-dom` in `build.rollupOptions.external` so consumers get a single copy of Merid's context and styles.

---

# Tailwind CSS

Merid and Tailwind coexist cleanly because both use cascade layers. The only thing to decide is their order.

## Layer order

Merid puts everything in `merid.tokens`, `merid.base` and `merid.components`. Tailwind v4 uses `theme`, `base`, `components` and `utilities`. Declare the order once, before either stylesheet:

```css
/* app.css */
@layer theme, base, merid, components, utilities;

@import "tailwindcss";
@import "@meridui/react/styles.css";
```

With this order:

- Tailwind's Preflight (`base`) comes first, so Merid's base and component styles win over it.
- Tailwind utilities come last, so `className="mt-4 w-full"` on a Merid component overrides the component's own spacing and width — without `!important`.
- Your own unlayered CSS still beats both.

If you import Merid from JavaScript instead (`import "@meridui/react/styles.css"`), keep the `@layer` statement at the top of the CSS file that Tailwind processes, and make sure that file loads first. Without the statement, or with Merid imported first, Preflight ends up above Merid and buttons and inputs lose their padding, borders and background. `npx @meridui/cli init` sets this up in Next.js, Vite and React Router projects, and `npx @meridui/cli doctor` warns when the order is wrong.

## Preflight

Preflight resets borders to `0 solid`, removes button backgrounds and makes images `display: block`. Merid's component rules restate everything they need, so components are unaffected. One thing to know:

- Preflight sets `border-color` to `currentColor` on every element. Merid hairlines use `--mrd-line`; if you draw your own borders with Tailwind, use the token: `border border-[var(--mrd-line)]` or the theme colour below.

## Tokens in the Tailwind theme

Map Merid's CSS variables into Tailwind with `@theme inline`, so utilities follow light and dark mode automatically:

```css
@theme inline {
  --color-accent: var(--mrd-accent);
  --color-accent-soft: var(--mrd-accent-soft);
  --color-ink: var(--mrd-ink);
  --color-body: var(--mrd-body);
  --color-muted: var(--mrd-muted);
  --color-line: var(--mrd-line);
  --color-surface: var(--mrd-surface);
  --color-tray: var(--mrd-tray);
  --color-danger: var(--mrd-danger);

--radius-control: var(--mrd-radius-lg);
  --radius-card: var(--mrd-radius-card);

--shadow-sm: var(--mrd-shadow-sm);
  --shadow-md: var(--mrd-shadow-md);

--font-sans: var(--mrd-font-sans);
  --font-mono: var(--mrd-font-mono);
}
```

```tsx
<div className="rounded-card bg-tray p-6 text-body">
  <h2 className="text-ink font-semibold">Usage</h2>
  <p className="text-muted">Resets on the 1st.</p>
</div>
```

`inline` makes Tailwind emit `var(--mrd-…)` in each utility instead of copying the value, which is what keeps dark mode working. The `@meridui/tokens` package exports the same list as `cssVar` if you generate the theme from JavaScript.

## Dark mode variant

Merid switches on `data-theme="dark"`. Point Tailwind's `dark:` variant at the same attribute so both agree:

```css
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```

This drops Tailwind's default `prefers-color-scheme` behaviour. If you rely on the system setting without a toggle, keep Tailwind's default and let Merid follow the media query too — it does by default.

## Tailwind v3

Tailwind v3 emits its output unlayered, so all of it — Preflight included — beats Merid's layered rules. Disable Preflight (`corePlugins: { preflight: false }`) or scope it, and expect utilities to always win. Map tokens in `tailwind.config.js` with `colors: { accent: "var(--mrd-accent)" }`.

---

# Icons

Merid ships no icon set. Every slot that takes an icon accepts any React node, so [lucide-react](https://lucide.dev), Heroicons, Phosphor or your own SVGs all work. Lucide's 24px grid and round joins match Merid's geometry best.

```bash
npm i lucide-react
```

```tsx
import { Plus, Search, Settings } from "lucide-react";

const ICON = { size: 16, strokeWidth: 1.75, "aria-hidden": true } as const;
const ICON_SM = { size: 14, strokeWidth: 1.75, "aria-hidden": true } as const;

<Button variant="primary" leadingIcon={<Plus {...ICON} />}>New project</Button>
<IconButton label="Settings" icon={<Settings {...ICON} />} />
<Input leading={<Search {...ICON_SM} />} placeholder="Search projects" aria-label="Search projects" />
<SidebarNav.Item href="/inbox" icon={<Mail {...ICON} />}>Inbox</SidebarNav.Item>
```

## Sizes

| Where | Size | Stroke |
|---|---|---|
| `Button` (`leadingIcon`, `trailingIcon`), `IconButton`, `SidebarNav.Item` | 16px | 1.75 |
| `Input` `leading` / `trailing`, `Badge`, dense table cells | 14px | 1.75 |
| `EmptyState` `icon`, `Alert` `icon` | 20px | 1.5 |

Lucide's default stroke of 2 reads heavier than Merid's 1.5px text and hairlines at 16px; 1.75 matches the weight of `medium` labels. Keep one set of props in a constant so every icon stays consistent.

## Accessibility

- Icons next to text are decorative: pass `aria-hidden`. `Button` and `Input` already wrap their icon slots in `aria-hidden` spans, so this is belt and braces.
- `IconButton` requires `label`, which becomes the accessible name (and tooltip text if you wrap it in `Tooltip`). The icon itself stays hidden.
- Never use an icon alone to carry meaning in a `Badge` or table cell; add text or a `VisuallyHidden` label.

## Colour

Icons use `currentColor`, so they follow the text tone of their slot — muted in inputs, ink in ghost buttons, white on primary. Do not colour icons with the accent unless the whole control is accented.

## Your own SVGs

Draw on a 16 or 20 unit grid, stroke `currentColor`, no fill, round caps. Give the `<svg>` `aria-hidden="true"` and `focusable="false"` (for old Edge).

```tsx
export function ProjectIcon(props: React.SVGProps<SVGSVGElement>) {
  return (
    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true" focusable="false" {...props}>
      <rect x="2.5" y="2.5" width="11" height="11" rx="3" stroke="currentColor" strokeWidth="1.4" />
    </svg>
  );
}
```

---

# Figma and Style Dictionary

`@meridui/tokens` publishes Merid's tokens in formats other tools read. It is generated from the same `tokens.css` that `@meridui/react` ships, and a test fails the build if the two ever disagree.

```bash
npm i @meridui/tokens
```

| Import | Format | Use it for |
|---|---|---|
| `@meridui/tokens/tokens.json` | [W3C Design Tokens](https://www.designtokens.org/tr/drafts/format/) (`$value`, `$type`) | Style Dictionary v4+, Terrazzo, other DTCG tools |
| `@meridui/tokens/figma-tokens.json` | Tokens Studio for Figma | Syncing variables and styles in Figma |
| `@meridui/tokens` | ES module + types | Raw values and `var()` references in JS |
| `@meridui/tokens/tokens.css` | CSS | A copy of the source, for non-React stacks |

## Token groups

`color`, `space`, `radius`, `typography`, `shadow`, `motion`, `size` (control heights, layout widths) and `z`. Each token keeps its CSS name in `$extensions["com.merid"].cssVariable`.

```json
"accent": {
  "$value": "#3f63f5",
  "$type": "color",
  "$extensions": {
    "com.merid": { "cssVariable": "--mrd-accent", "modes": { "dark": "#6b8aff" } }
  }
}
```

`$value` is the light (default) value. Dark values, and the responsive and touch overrides (`viewport-md`, `viewport-sm`, `pointer-coarse`), live under `modes`.

## Figma (Tokens Studio)

1. In Tokens Studio, add a sync provider (GitHub, URL, or JSON file) pointing at `figma-tokens.json`.
2. The file contains three sets — `core`, `dark` and `pointer-coarse` — and two themes, **Light** (`core`) and **Dark** (`core` as source + `dark`).
3. Use **Create variables** with both themes selected to get a Figma variable collection with Light and Dark modes.

Shadows come across as `boxShadow` tokens; duration, easing and z-index are typed `other` and are best left out of Figma variables.

## Style Dictionary

Style Dictionary v4 reads DTCG natively. Use it to emit tokens for platforms Merid does not target, such as iOS, Android or email templates:

```js
// sd.config.mjs
import StyleDictionary from "style-dictionary";

const sd = new StyleDictionary({
  source: ["node_modules/@meridui/tokens/dist/tokens.json"],
  platforms: {
    ios: { transformGroup: "ios-swift", buildPath: "ios/", files: [{ destination: "Merid.swift", format: "ios-swift/class.swift" }] },
    scss: { transformGroup: "scss", buildPath: "scss/", files: [{ destination: "_merid.scss", format: "scss/variables" }] },
  },
});

await sd.buildAllPlatforms();
```

For a dark build, add a small preprocessor that swaps `$value` for `$extensions["com.merid"].modes.dark` where present.

## JavaScript

```ts
import { tokens, cssVar } from "@meridui/tokens";

tokens.light.accent; // "#3f63f5"
tokens.dark.accent; // "#6b8aff"
cssVar.accent; // "var(--mrd-accent)"
```

In the browser, prefer `cssVar`: it follows the active theme. Reach for raw `tokens` only where CSS variables are not available — canvas, charts rendered to images, emails, native code.

## Changing tokens

Tokens are defined once, in `packages/react/styles/tokens.css`. Edit there, then run `npm run build -w @meridui/tokens`. The build fails if the `[data-theme="dark"]` block and the `prefers-color-scheme: dark` block drift apart.

---

# Plain HTML and CSS

Merid's styles depend only on class names, data attributes and ARIA state — never on React. Server-rendered templates (Rails, Django, Laravel, Astro, plain HTML) can use the stylesheet directly for everything that does not need JavaScript behaviour.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@meridui/react/dist/styles.css" />
<html>
```

The preview below is rendered as plain markup — no Merid component code runs.

```tsx
<div class="mrd-field">
  <label class="mrd-label" for="email">Email</label>
  <input id="email" class="mrd-input" data-size="md" type="email" />
  <p class="mrd-field__description">We only use it for receipts.</p>
</div>

<button class="mrd-button" data-variant="primary" data-size="md">
  <span class="mrd-button__content">Create account</span>
</button>
```

## What works without JavaScript

| Works with markup only | Needs your own script | Needs React |
|---|---|---|
| Button, IconButton, Link, Badge, Card, Alert, Separator, Spinner, Skeleton, Progress, Kbd, Code, Avatar (image or initials), Table, EmptyState, Heading, Text, Stack, Grid, Container, Section, Label, Field, Input, Textarea, NativeSelect, Checkbox, Radio, Breadcrumb, SidebarNav | Switch (toggle `data-state` and `aria-checked`), Tabs, SegmentedControl, Accordion (or use `<details>`), Pagination (as links) | Dialog, AlertDialog, Drawer, Popover, Tooltip, DropdownMenu, Select, Toast — focus trapping, positioning and dismissal live in the React code |

For overlays in a non-React page, use the native `<dialog>` element and style it yourself with Merid tokens, or mount the React component as an island.

## Markup reference

### Button

### Field with error

```html
<div class="mrd-field" data-invalid>
  <label class="mrd-label" for="user">Username</label>
  <input id="user" class="mrd-input" data-size="md" data-invalid aria-invalid="true" aria-describedby="user-error" />
  <p id="user-error" class="mrd-field__error">That username is taken.</p>
</div>
```

### Checkbox

```html
<span class="mrd-checkbox">
  <span class="mrd-checkbox__control">
    <input id="terms" type="checkbox" class="mrd-checkbox__input" />
    <svg class="mrd-checkbox__icon" viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path d="M3.5 8.5l3 3 6-7" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
    </svg>
  </span>
  <span class="mrd-checkbox__text">
    <label for="terms" class="mrd-checkbox__label">I agree to the terms</label>
  </span>
</span>
```

### Badge and alert

```html
<span class="mrd-badge" data-tone="success"><span class="mrd-badge__dot" aria-hidden="true"></span>Live</span>

<div class="mrd-alert" data-tone="warning" role="status">
  <div class="mrd-alert__content">
    <div class="mrd-alert__title">Payment method expiring</div>
    <div class="mrd-alert__body">Update it before 1 October.</div>
  </div>
</div>
```

### Card and table

```html
<article class="mrd-card" data-variant="outline" data-padding="md">…</article>

<div class="mrd-table-frame">
  <table class="mrd-table" data-density="md">
    <thead class="mrd-table__head"><tr class="mrd-table__row"><th class="mrd-table__header" scope="col">Name</th></tr></thead>
    <tbody class="mrd-table__body"><tr class="mrd-table__row"><td class="mrd-table__cell">Northwind</td></tr></tbody>
  </table>
</div>
```

## Finding the markup for anything else

Render the React component once and copy its HTML from the browser's element inspector — the output is stable, and class and attribute names are part of Merid's public API ([Versioning](https://meridui.dev/docs/versioning)). Each component page also lists its classes and data attributes under **Styling**.

---

# Subtree attributes

Three attributes switch Merid's tokens for an element and everything inside it. They work on `<html>` or on any element, need no provider, and nest in any combination.

| Attribute | Values | Default |
|---|---|---|
| `data-theme` | `light`, `dark` | follows `prefers-color-scheme` |
| `data-accent` | `blue`, `violet`, `green`, `graphite` | `blue` |
| `data-density` | `compact`, `default`, `comfortable` | `default` |

```tsx
<div data-theme="dark">
  <Sample />
  <div data-theme="light" data-accent="violet" data-density="compact">
    <Sample />
  </div>
</div>
```

## data-theme

Sets every neutral and accent token for the subtree. A light panel inside a dark page, or a dark panel inside a light one, is correct in both directions — the inner attribute always wins.

```html
<html data-theme="dark">          
  <aside data-theme="light">…</aside> 
</html>
```

Without any attribute, `:root` follows the operating system. The attribute sets tokens only: give the themed element a background (`background: var(--mrd-bg)` or `var(--mrd-tray)`) so its text sits on the right surface.

## data-accent

Swaps the whole accent family — `--mrd-accent`, `-hover`, `-soft`, `-strong`, `-solid`, `-solid-hover`, the focus ring and the primary button's contact shadow — in both themes. Each preset is contrast-checked in light and dark (solid fills carry white text at ≥ 4.5:1).

```html
<section data-accent="green">…</section>
```

`data-accent` and `data-theme` are independent: set them on the same element or on different ancestors. For a brand colour outside the four presets, override the tokens yourself — see [Theming a brand](https://meridui.dev/docs/integrations/theming).

## data-density

Changes control heights, control padding and the two small text sizes:

| | `compact` | `default` | `comfortable` |
|---|---|---|---|
| Button / select (`md`) | 28px | 32px | 36px |
| Input (`md`) | 28px | 32px | 36px |
| Icon button (`md`) | 24px | 28px | 32px |
| `--mrd-text-sm` | 13px | 14px | 14.5px |

Density applies to fine pointers only. On touch screens (`pointer: coarse`) Merid always uses its larger touch sizes (40px controls, 44px inputs), so `compact` never produces targets that are too small to tap.

## Reading the active values in JavaScript

The attributes are plain CSS, so read the resolved value from the element:

```ts
const accent = getComputedStyle(element).getPropertyValue("--mrd-accent").trim();
```

For static values (charts rendered to images, emails, native apps) use [`@meridui/tokens`](https://meridui.dev/docs/integrations/design-tokens), which exports every theme × accent and density combination.

## Direction (RTL)

The attributes combine with `dir="rtl"`. Component CSS uses logical properties only, the pagination chevrons and switch thumb mirror under `:dir(rtl)`, and arrow keys in RadioGroup and SegmentedControl follow the visual direction. See [Internationalization and RTL](https://meridui.dev/docs/integrations/rtl) for what is and is not covered.

## Forced colours

In Windows High Contrast and other forced-colour modes the attributes have no visible effect — the system palette replaces all colours, by design. Merid stays usable there: buttons, inputs, selects, segmented items and pagination get a 1px `ButtonText` border; checkboxes, radios and switches draw with `Canvas` / `ButtonText` and fill with `Highlight` when on; focus is a 2px `Highlight` outline; the selected tab, page and segment get a `Highlight` outline; and floating surfaces (card, dialog, drawer, popover, menu, select list, toast, tooltip) get a `CanvasText` border. Density still applies.

---

# Theming a brand

Merid has one accent colour. If one of the built-in presets is close enough, use it — `data-accent="violet"`, `"green"` or `"graphite"` on any element ([Subtree attributes](https://meridui.dev/docs/integrations/subtree-attributes)). For your own brand colour, override the accent family in your CSS. Because Merid lives in cascade layers, a plain unlayered rule wins with no `!important`.

```tsx
.brand-teal {
  --mrd-accent: #0f766e;
  --mrd-accent-hover: #0d6560;
  --mrd-accent-solid: #0f766e;
  --mrd-accent-solid-hover: #0d6560;
  --mrd-accent-soft: #e7f5f3;
  --mrd-accent-strong: #0b4f4a;
  --mrd-focus-ring: 0 0 0 3px rgb(15 118 110 / 20%);
}
```

## The accent family

| Token | Used for | Rule of thumb |
|---|---|---|
| `--mrd-accent` | links, focus outline, selected tab underline, checked controls | ≥ 3:1 against `--mrd-bg` (non-text) and ≥ 4.5:1 if used for link text |
| `--mrd-accent-hover` | hover of the above | about one step darker (light) or lighter (dark) |
| `--mrd-accent-solid` / `-solid-hover` | primary button fill, solid badge | ≥ 4.5:1 against `--mrd-on-accent` |
| `--mrd-on-accent` | text and icons on solid fills | usually `#fff`; set dark text for very light brands |
| `--mrd-accent-soft` | selected row, accent badge, icon tile | a 5–10% tint of the accent |
| `--mrd-accent-strong` | text on `accent-soft` | ≥ 4.5:1 against `accent-soft` |
| `--mrd-focus-ring` | the soft halo around focused controls | the accent at 18–28% opacity |

Override all of them together. Changing only `--mrd-accent` leaves the primary button and soft tints on the default blue.

## Whole app, light and dark

```css
/* brand.css — load after @meridui/react/styles.css */
:root,
[data-theme="light"] {
  --mrd-accent: #0f766e;
  --mrd-accent-hover: #0d6560;
  --mrd-accent-solid: #0f766e;
  --mrd-accent-solid-hover: #0d6560;
  --mrd-accent-soft: #e7f5f3;
  --mrd-accent-strong: #0b4f4a;
  --mrd-focus-ring: 0 0 0 3px rgb(15 118 110 / 20%);
}

[data-theme="dark"] {
  --mrd-accent: #2dd4bf;
  --mrd-accent-hover: #5eead4;
  --mrd-accent-solid: #0f766e;
  --mrd-accent-solid-hover: #115e59;
  --mrd-accent-soft: rgb(45 212 191 / 12%);
  --mrd-accent-strong: #99f6e4;
  --mrd-focus-ring: 0 0 0 3px rgb(45 212 191 / 28%);
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* same values as [data-theme="dark"] */
  }
}
```

In dark mode the text accent gets lighter, but the solid fill usually stays dark enough to carry white text — the same split Merid's own blue uses.

## One subtree

Everything is a custom property, so a class or attribute on any element themes just that part of the page — a partner's embedded widget, a marketing section, a per-workspace colour:

```tsx
<section className="brand-teal">
  <Button variant="primary">Start trial</Button>
</section>
```

For per-customer colours at runtime, set the properties inline: `style={{ "--mrd-accent": workspace.color, … } as React.CSSProperties}`. Validate contrast on the server before accepting a colour; a pale brand colour on white is not readable.

## Beyond colour

The same approach works for every token:

```css
:root {
  --mrd-font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --mrd-radius-lg: 6px;   /* controls */
  --mrd-radius-card: 10px;
}
```

For size, use `data-density` rather than overriding control heights one by one. Keep the design contract in mind: one accent, hairline borders, soft ink-tinted shadows. A brand colour changes the accent, not the rules.

---

# Dark mode strategies

Merid's tokens have a light and a dark value. Which one applies is decided by one attribute, `data-theme`, and the `prefers-color-scheme` media query. The token values themselves are listed in [Dark mode](https://meridui.dev/docs/foundations/dark-mode).

## 1. Follow the system

Do nothing. With no `data-theme` on `<html>`, Merid follows the operating system and switches live when it changes. Add `color-scheme` awareness to your own CSS by using the tokens (`var(--mrd-bg)`, `var(--mrd-ink)`) instead of fixed colours.

## 2. A toggle

Store the choice, apply it to `<html>` before first paint, and fall back to the system when nothing is stored.

```tsx
// Inline in <head>, before any CSS-dependent paint.
const themeInitScript = `
try {
  const t = localStorage.getItem("theme");
  if (t === "light" || t === "dark") document.documentElement.dataset.theme = t;
} catch {}`;
```

```tsx
"use client";
import { SegmentedControl } from "@meridui/react";

type Choice = "system" | "light" | "dark";

export function ThemeSwitcher() {
  const [choice, setChoice] = useState<Choice>("system");
  useEffect(() => {
    const t = document.documentElement.dataset.theme;
    setChoice(t === "light" || t === "dark" ? t : "system");
  }, []);
  return (
    <SegmentedControl
      aria-label="Theme"
      value={choice}
      onValueChange={(v) => { setChoice(v as Choice); apply(v as Choice); }}
      options={[
        { value: "system", label: "System" },
        { value: "light", label: "Light" },
        { value: "dark", label: "Dark" },
      ]}
    />
  );
}
```

In Next.js put the script in the root layout's `<head>` with `dangerouslySetInnerHTML` and add `suppressHydrationWarning` to `<html>`. `localStorage` can throw (private mode, blocked storage), so both reads and writes are wrapped.

To sync across tabs, listen for the `storage` event and re-apply.

## 3. Per subtree

`data-theme` works on any element and nests in both directions: a dark panel in a light page, or a light card in a dark one.

```tsx
<div data-theme="dark" style={{ background: "var(--mrd-bg)", padding: 16 }}>
  <Card variant="outline">…</Card>
</div>
```

The attribute sets tokens; it does not paint. Give the element a background from the tokens so its contents sit on the right surface. Accent presets and density nest the same way — see [Subtree attributes](https://meridui.dev/docs/integrations/subtree-attributes).

Portalled content (Dialog, Popover, DropdownMenu, Select, Tooltip, Toast) renders into `document.body` and so takes the page theme, not the subtree's. To keep an overlay in a subtree's theme, pass `container` (where the component supports it) pointing at an element inside the subtree.

## Images and charts

- Use `<picture>` with `media="(prefers-color-scheme: dark)"` only when you follow the system. With a toggle, switch sources on `[data-theme="dark"]` in CSS instead.
- For charts, read colours from CSS variables at render time (`getComputedStyle(el).getPropertyValue("--mrd-accent")`) and re-render on theme change.

---

# Internationalization and RTL

Merid has no locale system of its own. Components render the strings you pass them, and layout follows the document direction. This page is honest about what that covers.

```tsx
<div dir="rtl" lang="ar">
  <Field label="البحث" description="ابحث بالاسم أو المعرّف.">
    <Input leading={<Search size={14} aria-hidden />} placeholder="ابحث…" />
  </Field>
  <Switch defaultChecked>الإشعارات</Switch>
  <Pagination pageCount={8} defaultPage={3} previousLabel="السابق" nextLabel="التالي" />
</div>
```

## Right-to-left

Set `dir="rtl"` (and `lang`) on `<html>`, or on any subtree.

| Area | Status |
|---|---|
| Layout, spacing, borders, radii | Supported. Component CSS uses logical properties only (`padding-inline`, `inset-inline-end`, …); a test forbids physical `left` / `right`. |
| Input leading / trailing addons, NativeSelect chevron | Supported — they swap sides. |
| Switch thumb | Supported — travels right-to-left under `:dir(rtl)`. |
| Pagination chevrons | Supported — mirror under `:dir(rtl)`. |
| Arrow keys in RadioGroup and SegmentedControl | Supported — ArrowLeft moves to the visually left item. |
| Arrow keys in Tabs | **Not yet.** ArrowRight / ArrowLeft follow DOM order, so in RTL they move the opposite way to what is on screen. Tracked as a library bug. |
| Select / Accordion chevrons, breadcrumb separator | Vertical or direction-neutral; no flip needed. |
| `Drawer side="left" \| "right"` | Physical by design. Pick the side from the direction yourself: `side={dir === "rtl" ? "left" : "right"}`. |
| Your icons (arrows, "back" chevrons) | Not flipped automatically. Mirror directional icons with `:dir(rtl) .icon-arrow { transform: scaleX(-1) }`. |

## Strings

Every visible or announced string is a prop, so translate them like any other text:

- `Pagination`: `previousLabel`, `nextLabel`, `pageLabel(page)`, `aria-label`.
- `Spinner` (`label`) and icon-only close buttons have English default labels; pass translated `label` / `aria-label` props.
- `IconButton`: `label` is required, so it is always yours.
- `Avatar`: initials come from `getInitials(name)`, which takes the first letters of the first and last word. Pass `initials` for scripts where that is wrong (e.g. CJK names).

## Numbers, dates and currency

Format before rendering with `Intl`:

```tsx
const money = new Intl.NumberFormat(locale, { style: "currency", currency: "EUR" });
<TableCell align="end"><Text as="span" numeric>{money.format(amount)}</Text></TableCell>
```

`align="end"` puts numbers on the correct side in both directions. `Text numeric` turns on tabular figures.

## Fonts

The bundled Geist is designed for Latin scripts. Arabic, Hebrew, CJK, Devanagari and others fall back through `--mrd-font-sans` to the system font. For a consistent look, put a font for your script first:

```css
:root:lang(ar) {
  --mrd-font-sans: "IBM Plex Sans Arabic", "Geist", ui-sans-serif, system-ui, sans-serif;
}
```

Negative heading tracking is tuned for Latin; reset it for connected scripts: `:lang(ar) { --mrd-tracking-display: 0; --mrd-tracking-h2: 0; --mrd-tracking-h3: 0; }`.

---

# Forms

A form is a `Card` (or a plain section), a heading, a `Grid` or `Stack` of `Field`s, and one primary action at the end. Submit it once with an invalid email to see validation, then with an address ending in `@fail.test` to see the server error.

```tsx
<form onSubmit={onSubmit} noValidate aria-busy={busy}>
  <Stack gap={6}>
    {status === "error" ? <Alert tone="danger" title="We could not send your request" live="assertive">…</Alert> : null}
    <Grid columns={2} gap={4} minItemWidth={200}>
      <Field label="Full name" required error={errors.name}><Input name="name" autoComplete="name" /></Field>
      <Field label="Work email" required error={errors.email}><Input name="email" type="email" /></Field>
    </Grid>
    <Field label="What are you building?" description="Optional."><Textarea name="notes" rows={3} /></Field>
    <Separator />
    <Stack direction="row" gap={2} justify="end">
      <Button type="reset" variant="ghost">Clear</Button>
      <Button type="submit" variant="primary" loading={busy}>Send request</Button>
    </Stack>
  </Stack>
</form>
```

## Layout

- **One column** by default. Put two short, related fields side by side (first and last name, city and postcode) with `Grid columns={2} minItemWidth={200}` — it drops to one column when there is no room.
- **Labels above controls**, always visible. Placeholders are examples, never labels.
- **`gap={6}` between groups, `gap={4}` between fields.** A `Separator` before the actions marks the end of the form.
- **Actions at the end, aligned to the end.** Primary on the outside, secondary (ghost) next to it. A form has one primary button.
- Mark required fields with `required` on `Field`; if most fields are optional, mark the required ones and say so once at the top instead.

## Validation timing

| When | What |
|---|---|
| While typing | Nothing. Do not flag a field the user has not finished. |
| On blur | Validate the field that was left, if it has a value. |
| On submit | Validate everything, show every error, move focus to the first invalid field. |
| After an error | Re-validate that field on each change so the message clears as soon as it is fixed. |

`Field`'s `error` prop does the ARIA wiring: `aria-invalid` on the control and the message in `aria-describedby`. Moving focus to the first invalid control lets screen reader users hear the error immediately:

```tsx
event.currentTarget.querySelector<HTMLElement>("[aria-invalid='true']")?.focus();
```

Use `noValidate` on the form so the browser's own bubbles do not compete with Field's messages, but keep `type="email"`, `autoComplete` and `inputMode` — they drive mobile keyboards and autofill.

## Submit states

- **Submitting.** `Button loading` keeps its width, shows a spinner, sets `aria-busy` and ignores clicks. Disable the fields too, and set `aria-busy` on the form.
- **Server error.** An `Alert tone="danger"` at the top of the form, with `live="assertive"`. Keep the user's input. Say what happened and whether anything was saved.
- **Success.** Either navigate away, or show an `Alert tone="success"` in place and reset. For small saves (settings), a toast is enough — see [Settings pages](https://meridui.dev/docs/patterns/settings).

## Error messages

Say what to do, not what went wrong: "Enter a valid work email", not "Invalid input". Keep them to one line. Never clear a field because it was invalid.

## With a form library

The same layout works with React Hook Form or Zod — see [React Hook Form](https://meridui.dev/docs/integrations/react-hook-form) and [Validation with Zod](https://meridui.dev/docs/integrations/zod).

---

# Empty and loading states

Every view that loads data has four states: loading, empty, error and ready. Design all four; switch between them below.

```tsx
<Card variant="outline" aria-busy={loading} aria-live="polite">
  {loading ? (<><VisuallyHidden>Loading members…</VisuallyHidden><ListSkeleton /></>) : null}
  {empty ? (
    <EmptyState variant="plain" icon={<PeopleIcon />} title="No members yet"
      description="Invite teammates to share projects and review changes together."
      action={<Button variant="primary">Invite people</Button>} />
  ) : null}
  {error ? (
    <Alert tone="danger" title="Members could not be loaded" action={<Button size="sm" onClick={retry}>Retry</Button>}>
      The server took too long to respond.
    </Alert>
  ) : null}
  {ready ? <MemberList /> : null}
</Card>
```

## Loading

| Situation | Use |
|---|---|
| Content with a known shape (lists, cards, tables) | `Skeleton` blocks that match the final layout |
| An action the user just triggered | `Button loading` on that button |
| Background work with no layout to hold | `Spinner size="sm"` with a short label |
| Long, measurable work (uploads, imports) | `Progress` with a value |

- Match the skeleton to the real content: same row height, avatar size and line count. The page should not jump when data arrives.
- Skeletons are decorative. Hide them with `aria-hidden` and announce loading once with `VisuallyHidden` text inside an `aria-live` region, or `aria-busy` on the container.
- Wait about 300ms before showing a loader for fast requests, so it does not flash.

```tsx
<Button variant="primary" loading={saving} onClick={save}>Save changes</Button>
<Stack direction="row" gap={2} align="center">
  <Spinner size="sm" label={null} />
  <Text size="sm" tone="muted">Syncing 3 files…</Text>
</Stack>
```

`Spinner` has a built-in accessible label; pass `label={null}` when visible text next to it already says what is happening.

## Empty

An empty state explains what will be here and offers the one action that fills it.

- **First use:** icon, a title that names the thing ("No members yet"), one sentence of value, one primary action.
- **No results:** no icon or action needed. Repeat the query and offer to clear filters: "No invoices match “fabrikam”."
- **Cleared / done:** "You're all caught up" — no action.

Use `variant="plain"` inside a card or panel that already has a surface, and the default `tray` variant when the empty state fills a page region by itself.

## Error

Use an `Alert tone="danger"` in place of the content, with a Retry `action`. Say what failed in plain words; do not show stack traces or status codes to end users. If part of the page loaded, keep it and show the error only where data is missing.

---

# Confirmations and destructive actions

Confirmation dialogs interrupt. Use them only when an action cannot be undone; for everything else, do it immediately and offer Undo.

| Action | Pattern |
|---|---|
| Reversible (archive, hide, move, mark as read) | Do it now, show a toast with **Undo** |
| Irreversible, low stakes (delete a draft, remove a filter) | `AlertDialog` with a clear verb |
| Irreversible, high stakes (delete a project, revoke all keys, transfer ownership) | `AlertDialog` with a typed confirmation |

## Undo instead of confirm

```tsx
toast({
  id: "archive",
  title: "Project archived",
  description: "It is hidden from the dashboard.",
  duration: 8000,
  action: { label: "Undo", onClick: restore },
});
```

Give the toast a stable `id` so repeated clicks replace it rather than stack, and a longer `duration` so there is time to react.

## Typed confirmation

```tsx
<AlertDialog.Root onOpenChange={(open) => !open && setTyped("")}>
  <AlertDialog.Trigger asChild>
    <Button variant="danger">Delete project</Button>
  </AlertDialog.Trigger>
  <AlertDialog.Content>
    <AlertDialog.Title>Delete “northwind”?</AlertDialog.Title>
    <AlertDialog.Description>
      This removes 24 deployments, 3 domains and all environment variables. It cannot be undone.
    </AlertDialog.Description>
    <Field label="Type northwind to confirm">
      <Input value={typed} onChange={(e) => setTyped(e.target.value)} autoComplete="off" />
    </Field>
    <AlertDialog.Footer>
      <AlertDialog.Cancel>Cancel</AlertDialog.Cancel>
      <AlertDialog.Action tone="danger" disabled={typed !== "northwind"} onClick={remove}>
        Delete project
      </AlertDialog.Action>
    </AlertDialog.Footer>
  </AlertDialog.Content>
</AlertDialog.Root>
```

## Writing the dialog

- **Title is a question with the object:** "Delete “northwind”?" — not "Are you sure?".
- **Description states the consequence** in concrete numbers, and says it cannot be undone.
- **The confirm button repeats the verb:** "Delete project", never "OK" or "Yes".
- **Cancel is the safe default.** `AlertDialog` focuses Cancel when it opens, so pressing Enter by reflex does nothing destructive. Clicking the backdrop does not dismiss it; Escape acts as Cancel.
- Use `tone="danger"` on the action only when it destroys something.

## Where the button lives

Keep destructive actions away from the primary path. On a settings page, put them in a separate section at the bottom ("Danger zone"), with a `danger` button that opens the dialog — never a primary button that deletes directly.

---

# Data tables

Merid's `Table` is a styled semantic `<table>`, not a data grid. Sorting, selection and paging are a few lines of state around it, which keeps you in control of what runs on the server.

```tsx
<Table hoverable scrollLabel="Invoices">
  <TableHead>
    <TableRow>
      <TableHeader><Checkbox aria-label="Select all on this page" checked={allOnPage}
        indeterminate={someOnPage && !allOnPage} onChange={togglePage} /></TableHeader>
      <TableHeader>Invoice</TableHeader>
      <TableHeader aria-sort={sort.key === "customer" ? sort.dir : "none"}>
        <Button variant="ghost" size="sm" onClick={() => onSort("customer")}>Customer ↑</Button>
      </TableHeader>
      <TableHeader align="end">Amount</TableHeader>
    </TableRow>
  </TableHead>
  <TableBody>
    {visible.map((row) => (
      <TableRow key={row.id} selected={selected.has(row.id)}>
        <TableCell><Checkbox aria-label={`Select ${row.id}`} checked={selected.has(row.id)} onChange={() => toggle(row.id)} /></TableCell>
        …
      </TableRow>
    ))}
  </TableBody>
</Table>
<Pagination pageCount={pageCount} page={page} onPageChange={setPage} />
```

## Sorting

- Make the header label a ghost `Button` and set `aria-sort` (`ascending`, `descending` or `none`) on the `TableHeader`. Screen readers announce the sort state when entering the column.
- Show a direction arrow on the active column; a faint arrow on sortable inactive columns signals they can be sorted.
- First click sorts ascending (A–Z, low–high); clicking again reverses.

## Selection and bulk actions

- A checkbox column, with a header checkbox that selects the **current page** and goes `indeterminate` when some rows are selected.
- `TableRow selected` paints the accent-soft fill. The checkbox carries the state for assistive tech; `selected` is visual only.
- Put bulk actions in the toolbar above the table, disabled until something is selected, and replace the row count with "3 selected" in an `aria-live` region.
- Keep selection when paging; clear it when the filter changes the data set, or say how many selected rows are hidden.

## Pagination and filtering

- Reset to page 1 whenever the filter or sort changes.
- Show "Page 2 of 4" or "21–30 of 230" next to `Pagination`.
- For server data, keep `page`, `sort` and the filter in the URL so views can be shared — see [React Router and TanStack](https://meridui.dev/docs/integrations/routers).
- Empty result: one full-width row (`colSpan`) that repeats the query. See [Empty and loading states](https://meridui.dev/docs/patterns/empty-and-loading).

## Numbers and alignment

Right-align numeric columns (`align="end"` on both header and cells) and use `Text numeric` for tabular figures so digits line up. Status goes in a `Badge`, never colour alone.

## Wide tables

`Table` wraps itself in a scroll frame. `scrollLabel` names that region so keyboard users can focus it and scroll horizontally. Use `density="sm"` for tables that users scan rather than read.

---

# Settings pages

A settings page is a `SidebarNav` of categories and a column of sections. Each section has a title and one sentence on the left, controls on the right, and collapses to one column on narrow screens.

```tsx
<form onChange={() => setDirty(true)} onSubmit={save}>
  <Stack gap={8}>
    <Section title="Profile" description="Shown on comments and in the member list.">
      <Field label="Display name"><Input name="name" defaultValue="Ada Lovelace" /></Field>
      <Field label="Time zone"><NativeSelect name="tz">…</NativeSelect></Field>
    </Section>
    <Separator />
    <Section title="Notifications" description="Email is sent at most once an hour.">
      <Switch name="mentions" defaultChecked>Mentions and replies</Switch>
    </Section>
    <Separator />
    <Stack direction="row" justify="end" gap={2} align="center">
      {dirty ? <Text size="sm" tone="muted">Unsaved changes</Text> : null}
      <Button type="submit" variant="primary" disabled={!dirty} loading={saving}>Save changes</Button>
    </Stack>
  </Stack>
</form>
```

## Save model

Pick one per page and stick to it:

- **Explicit save** (shown above) for text fields and anything that affects other people: a single Save button at the end, disabled until something changes, with "Unsaved changes" next to it. Confirm with a toast.
- **Instant apply** for pages that are only toggles (notification preferences, feature flags): each `Switch` saves on change and shows a toast on failure, reverting the switch. No Save button.

Never mix both in one section: users cannot tell which changes are saved.

## Structure

- Group by what users look for, not by data model: Account, Workspace, Billing, Security.
- `SidebarNav` marks the current category with `active`, which sets `aria-current="page"`. Each category is its own route.
- Sections separated by `Separator`, titles with `Heading size="sm"`, descriptions in muted text.
- Keep labels short and put the explanation in `Field`'s `description` or the Switch's label.

## Danger zone

Destructive account actions go last, in their own outlined card, with a `danger` button that opens a confirmation — see [Confirmations](https://meridui.dev/docs/patterns/confirmations).

```tsx
<Card variant="outline" padding="md">
  <Stack direction="row" gap={4} justify="between" align="center" wrap>
    <Stack gap={1}>
      <Text weight="medium" tone="ink" size="sm">Delete account</Text>
      <Text size="sm" tone="muted">Removes your profile and leaves every workspace.</Text>
    </Stack>
    <Button variant="danger" size="sm">Delete account</Button>
  </Stack>
</Card>
```

---

# Authentication screens

A centred `Card variant="elevated"` on the page background, a heading, the form and one primary action. Submit the form below to see the error state.

```tsx
<Card variant="elevated" padding="lg">
  <Heading level={1} size="h3">Sign in to Merid</Heading>
  <Button fullWidth>Continue with SSO</Button>
  <form onSubmit={onSubmit} noValidate>
    {failed ? <Alert tone="danger" live="assertive">That email and password do not match.</Alert> : null}
    <Field label="Email" error={emailError}>
      <Input name="email" type="email" autoComplete="username" />
    </Field>
    <Field label="Password">
      <Input name="password" type={show ? "text" : "password"} autoComplete="current-password" />
    </Field>
    <Checkbox checked={show} onChange={(e) => setShow(e.target.checked)}>Show password</Checkbox>
    <Button type="submit" variant="primary" fullWidth loading={submitting}>Sign in</Button>
  </form>
</Card>
```

## Autocomplete

Password managers depend on these attributes. Get them right and most users never type a password.

| Field | Attributes |
|---|---|
| Email / username on sign-in | `type="email" autoComplete="username"` |
| Current password | `type="password" autoComplete="current-password"` |
| New password (sign-up, reset) | `type="password" autoComplete="new-password"` |
| One-time code | `inputMode="numeric" autoComplete="one-time-code"` |

## Errors

- Do not reveal which part was wrong: "That email and password do not match", not "No account with that email". It prevents account enumeration.
- Show the error in an `Alert` above the fields with `live="assertive"`, keep the email, clear nothing else automatically.
- Client-side, validate only format (an `@` in the email). Everything else is the server's job.
- After repeated failures, say what happens next ("Try again in 5 minutes") rather than silently rate-limiting.

## Show password

A "Show password" `Checkbox` (or an `IconButton` in the input's trailing slot) switches `type` between `password` and `text`. It helps on mobile and is safer than a confirm-password field.

## Verification code

```tsx
<Field label="Verification code">
  <Input inputMode="numeric" autoComplete="one-time-code" maxLength={6}
    value={code} onChange={(e) => setCode(e.target.value.replace(/\D/g, ""))} />
</Field>
<Button variant="primary" fullWidth disabled={!/^\d{6}$/.test(code)}>Verify</Button>
```

Use a single input rather than six boxes: it pastes, autofills from SMS and email, and works with screen readers. Say where the code was sent and when it expires.

## Page layout

Centre the card with a grid: `place-items: center` and `min-height: 100dvh`. Keep the page quiet: logo, card, and a single footer link to help or terms.

---

# Navigation layouts

The standard app shell: a fixed sidebar on the tray surface, a top bar with breadcrumbs and account menu, and the page content on the background. On narrow screens the sidebar moves into a `Drawer` behind a menu button.

```tsx
<div className="shell">
  <aside className="shell__sidebar">
    <SidebarNav aria-label="Main">
      <SidebarNav.Item as={RouterLink} href="/" icon={<Home {...ICON} />} active>Overview</SidebarNav.Item>
      <SidebarNav.Item href="/inbox" icon={<Inbox {...ICON} />} trailing={<Badge>4</Badge>}>Inbox</SidebarNav.Item>
      <SidebarNav.Group label="Pinned">…</SidebarNav.Group>
    </SidebarNav>
  </aside>
  <div className="shell__main">
    <header className="shell__topbar">
      <Drawer.Root open={open} onOpenChange={setOpen}>
        <Drawer.Trigger asChild><IconButton label="Open navigation" icon={<Menu {...ICON} />} /></Drawer.Trigger>
        <Drawer.Content side="left" size="sm">…same SidebarNav…</Drawer.Content>
      </Drawer.Root>
      <Breadcrumb.Root>…</Breadcrumb.Root>
      <DropdownMenu.Root>
        <DropdownMenu.Trigger asChild><button aria-label="Account menu"><Avatar name="Ada Lovelace" size="sm" /></button></DropdownMenu.Trigger>
        <DropdownMenu.Content placement="bottom-end">…</DropdownMenu.Content>
      </DropdownMenu.Root>
    </header>
    <main className="shell__content">…</main>
  </div>
</div>
```

## The CSS

The shell is layout, so it is yours: a few lines of grid using Merid's tokens.

```css
.shell {
  display: grid;
  grid-template-columns: 240px minmax(0, 1fr);
  min-height: 100dvh;
}
.shell__sidebar {
  position: sticky;
  top: 0;
  height: 100dvh;
  overflow-y: auto;
  padding: var(--mrd-space-4) var(--mrd-space-3);
  background: var(--mrd-tray);
  border-inline-end: 1px solid var(--mrd-line);
}
.shell__topbar {
  position: sticky;
  top: 0;
  z-index: var(--mrd-z-sticky);
  display: flex;
  align-items: center;
  justify-content: space-between;
  height: 52px;
  padding-inline: var(--mrd-space-4);
  background: var(--mrd-bg);
  border-bottom: 1px solid var(--mrd-line);
}
.shell__content { padding: var(--mrd-space-8) var(--mrd-gutter); }
.shell__menu { display: none; }

@media (width < 720px) {
  .shell { grid-template-columns: minmax(0, 1fr); }
  .shell__sidebar { display: none; }
  .shell__menu { display: inline-flex; }
}
```

The preview uses a container query at 520px so it responds to the preview width, not the window; in an app, use the media query.

## Guidelines

- **One nav, two containers.** Render the same `SidebarNav` in the sidebar and in the drawer so they never drift. Close the drawer on navigation.
- **Active state comes from the route.** Pass `active` from the current path; it sets `aria-current="page"`. With a router, pass its link as `as` — see [Next.js](https://meridui.dev/docs/integrations/nextjs) and [React Router and TanStack](https://meridui.dev/docs/integrations/routers).
- **Group, don't nest.** Use `SidebarNav.Group` labels for sections. More than two levels of navigation belongs in the page (tabs), not the sidebar.
- **Top bar is for context and account**, not primary navigation: breadcrumbs on the start side, notifications and the account menu on the end side.
- **Landmarks.** The sidebar `nav` is labelled by `aria-label`; wrap page content in `<main>` and add a "Skip to content" link as the first focusable element.
- **Icons** at 16px with 1.75 stroke — see [Icons](https://meridui.dev/docs/integrations/icons).

## Variations

- **Top nav only**: for apps with fewer than six sections, drop the sidebar and use `Tabs` or links in the top bar.
- **Settings sub-nav**: a second `SidebarNav` inside the content area, as in [Settings pages](https://meridui.dev/docs/patterns/settings).

---

# Logo and usage

The Merid mark is a wave. Its two crests form an M, and the line runs on past them like a signal travelling along the meridian, the single reference line the library's layouts are drawn against. Where the line passes under itself it drops into shadow (ink in light mode, deep blue in dark), which gives the flat shape its depth without a gradient. The wave carries the accent; it is the one place the brand uses its blue at full strength. The mark pairs with a lowercase wordmark set in Geist SemiBold at -0.035em tracking, outlined to paths in the SVG files so it renders the same everywhere. In the lockup the wave sits on the wordmark's x-height, a touch taller so its crests overshoot the way round letters do.

## Versions

The mark on its own is available as [light](https://meridui.dev/brand/mark-light.svg), [dark](https://meridui.dev/brand/mark-dark.svg) and [mono](https://meridui.dev/brand/mark-mono.svg). A white mono logo is at [/brand/logo-mono-white.svg](https://meridui.dev/brand/logo-mono-white.svg) and the app icon at [/icon.svg](https://meridui.dev/icon.svg).

## Clear space

Keep clear space around the logo equal to half the height of the wave. Nothing else, including other logos and the edge of the frame, should enter that space.

## Minimum size

The full logo should be at least 72px wide on screen. Below that, use the mark alone at 10px tall or larger. At favicon sizes use the app icon: the white wave on an accent tile, with accent-strong shadows.

## Colour

Use the light version on white or `--mrd-tray`, and the dark version on `--mrd-bg` in dark mode. When colour is unavailable — engraving, single-colour print, a monochrome badge — use the mono version. The wave is always `#3f63f5` in light and `#6b8aff` in dark; its shadows are ink `#0f1219` in light and `#1a2a6e` in dark.

## Avoid

- **Do:** Use the supplied SVG files as they are. Place the logo on flat, calm backgrounds. Scale the logo proportionally.
- **Don't:** Recolour the wave, or drop or recolour its shadows. Redraw the crests or straighten the line. Add gradients, shadows, outlines or effects. Rotate, stretch or re-typeset the wordmark. Place the logo on busy photographs.

## Name

Write the name as **Merid** in running text, with a capital M. The wordmark is lowercase by design. The package is `@meridui/react`.