# SoybeanUI Docs

English LLM-friendly documentation bundle for the SoybeanUI docs site.

## Chart Demos

- Page URL: /chart
- Markdown URL: /chart.md
- Description: shadcn-styled chart demos built with TanStack Charts and SoybeanUI theme tokens.

# Charts

These charts render directly with [TanStack Charts](https://tanstack.com/charts), following the same usage as the [shadcn chart collection](https://tanstack.com/charts/catalog/collections/shadcn). SoybeanUI **no longer ships a dedicated chart wrapper package** — TanStack Charts is already a framework-agnostic chart grammar, and using it directly lets you follow the official upgrade path without being locked into an extra abstraction.

## How theming works

The demos bridge the theme with a lightweight `ChartContainer` + `chartConfig`:

- `chartConfig` maps each series field to `{ label, color }`;
- colors come from the theme tokens `hsl(var(--chart-1..5))`, and `ChartContainer` injects them as `--color-<key>` CSS custom properties on the wrapper;
- marks reference `var(--color-<key>)`, so colors follow light/dark theme changes automatically.

`ChartContainer` is only a config → CSS-variable styling bridge with **no chart logic**; treat it as a small component you can copy into your own project. TanStack Charts' built-in axes, grid, tooltip, and legend do the rest.

## Demos

Pick a chart type in the sidebar (or the cards below) to see live demos and copyable source.

## Installation

- Page URL: /chart/installation
- Markdown URL: /chart/installation.md
- Description: Install TanStack Charts and wire it into a SoybeanUI project.

# Installation

Charts are powered by [TanStack Charts](https://tanstack.com/charts). Install it directly (the Vue adapter ships in the same package):

```bash
pnpm add @tanstack/charts
```

## Import what you need

- Cartesian charts (bar/line/area/scatter): `defineChart`, `barY`, `lineY`, `areaY`, `dot`, and more from `@tanstack/charts`;
- scales: `@tanstack/charts/scales/band`, `@tanstack/charts/scales/linear`, `@tanstack/charts/scales/point`;
- the Vue component: `Chart` from `@tanstack/charts/vue`;
- tooltip: `tooltip` from `@tanstack/charts/tooltip`;
- polar (donut): `pie`, `polar`, `radialArc` from `@tanstack/charts/polar`.

The polar entry is an opt-in subpath — when not imported, the package keeps a Cartesian-sized footprint.

## Theme colors

Make sure the SoybeanUI theme is available (`@soybeanjs/ui/styles.css` or the UnoCSS preset) so tokens like `--chart-1..5` exist and the demo colors follow light/dark mode.

## Quick Start

- Page URL: /chart/quick-start
- Markdown URL: /chart/quick-start.md
- Description: Describe a chart with defineChart, render it with the Vue Chart component, and wire in SoybeanUI theme colors.

# Quick Start

TanStack Charts uses a declarative grammar: describe marks, scales, color, and tooltip with `defineChart`, then render it with the Vue `<Chart>` component.

## 1. Define the series config

```ts
const chartConfig = {
  desktop: { label: 'Desktop', color: 'hsl(var(--chart-1))' }
} satisfies ChartConfig;
```

## 2. Describe the chart

```ts
import { barY, defineChart } from '@tanstack/charts';
import { scaleBand } from '@tanstack/charts/scales/band';
import { scaleLinear } from '@tanstack/charts/scales/linear';
import { tooltip } from '@tanstack/charts/tooltip';

const chart = defineChart({
  marks: [
    barY(chartData, {
      x: 'month',
      y: 'desktop',
      fill: 'var(--color-desktop)'
    })
  ],
  scales: {
    x: { scale: () => scaleBand<string>().padding(0.16) },
    y: { scale: scaleLinear, nice: true, grid: true }
  },
  tooltip
});
```

## 3. Render

```vue

  <Chart :definition="chart" :height="250" aria-label="Desktop signups by month" />

```

`ChartContainer` exposes `chartConfig.desktop.color` as `--color-desktop`, so `var(--color-desktop)` resolves in the marks and follows the theme. For multiple series, hand the color domain to `color.range` (see the grouped bar demo).

## SoybeanUI CLI

- Page URL: /cli
- Markdown URL: /cli.md
- Description: sbean is the command-line tool for SoybeanUI. It helps you initialize projects, add components, and manage your UI configuration.

# SoybeanUI CLI

`sbean` is the command-line tool for SoybeanUI. It helps you initialize projects, add components, and manage your UI configuration.

## Installation

```bash
pnpm add -D sbean
```

Or run directly:

```bash
npx sbean init
```

## Commands

### `sbean init`

Initialize a new SoybeanUI project or add configuration to an existing one.

```bash
sbean init [options]
```

| Option                  | Description                                                                 | Default                                      |
| ----------------------- | --------------------------------------------------------------------------- | -------------------------------------------- |
| `-m, --monorepo`        | Use monorepo (pnpm workspaces) structure                                    | `false`                                      |
| `--ui-dir <path>`       | Component output directory                                                  | `src/ui` (single) / `packages/ui` (monorepo) |
| `--size <size>`         | Component size: xs / sm / md / lg / xl / 2xl                                | `md`                                         |
| `--style <style>`       | Style preset: soybean / clean / dense                                       | `soybean`                                    |
| `-b, --base <base>`     | Base color: zinc / neutral / stone / slate / gray                           | `zinc`                                       |
| `--primary <primary>`   | Primary color: indigo / blue / green / ...                                  | `indigo`                                     |
| `--radius <radius>`     | Border radius: none / xs / sm / md / lg / xl / 2xl                          | `md`                                         |
| `-p, --preset <code>`   | Preset code (base62 encoded config)                                         | —                                            |
| `--icon-library <lib>`  | Icon library: lucide / material-symbols / ph / tabler / solar / radix-icons | `lucide`                                     |
| `--font-sans <font>`    | Sans-serif font: inter / roboto / geist / ...                               | —                                            |
| `--font-heading <font>` | Heading font or `inherit`                                                   | —                                            |
| `-y, --yes`             | Skip confirmation prompt                                                    | `false`                                      |
| `-d, --defaults`        | Use default configuration                                                   | `false`                                      |
| `-f, --force`           | Overwrite existing configuration                                            | `false`                                      |

Interactive prompts will guide you through the configuration when no options are provided.

### `sbean add`

Add components to your project.

```bash
sbean add <component...> [options]
```

| Option              | Description                              |
| ------------------- | ---------------------------------------- |
| `-y, --yes`         | Skip confirmation prompt                 |
| `-o, --overwrite`   | Overwrite existing files                 |
| `-p, --path <path>` | Target path (default: uiDir from config) |
| `--dry-run`         | Preview changes without writing          |
| `--diff`            | Show diff between local and registry     |
| `--view`            | View component source without adding     |
| `-a, --all`         | Add all available components             |
| `-s, --silent`      | Mute output                              |

### `sbean build`

Build registry JSON files from a registry.json manifest.

```bash
sbean build [registry] [options]
```

| Option                | Description      | Default      |
| --------------------- | ---------------- | ------------ |
| `-o, --output <path>` | Output directory | `./public/r` |

### `sbean search`

Search for available components.

```bash
sbean search [query] [options]
```

| Option                  | Description                                            |
| ----------------------- | ------------------------------------------------------ |
| `-a, --all`             | Show all components                                    |
| `-t, --type <type>`     | Filter by type: component / hook / style / lib / theme |
| `-l, --limit <limit>`   | Max results (default: 50)                              |
| `-o, --offset <offset>` | Pagination offset                                      |

### `sbean list`

List registry items, optionally filtered by package.

```bash
sbean list [options]
```

| Option             | Description                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `--package <name>` | Filter by package namespace (currently: `ui`; future peripheral packages are added under their own namespace) |
| `--json`           | Output as JSON                                                                                                |

Items are namespaced by package (currently `ui/button`, `ui/accordion`, …; future peripheral packages follow `<package>/<component>`).

### `sbean view`

View a component's source code.

```bash
sbean view <component>
```

### `sbean info`

Show project configuration and available preset values.

```bash
sbean info [options]
```

| Option   | Description    |
| -------- | -------------- |
| `--json` | Output as JSON |

### `sbean template`

Scaffold a new project from a template.

```bash
sbean template [name] [options]
```

| Option               | Description              |
| -------------------- | ------------------------ |
| `-l, --list`         | List available templates |
| `-o, --output <dir>` | Output directory         |

Available templates: `vue-vite`, `nuxt`.

### `sbean preset`

Manage configuration presets.

```bash
sbean preset <preset>
```

## Configuration

The `sbean.json` file stores your project configuration:

```json
{
  "iconLibrary": "lucide",
  "uno": {
    "base": "zinc",
    "primary": "indigo",
    "size": "md",
    "radius": "md"
  },
  "font": {
    "sans": "inter",
    "heading": "inherit"
  },
  "aliases": {
    "ui": "#ui"
  },
  "registries": {}
}
```

| Field          | Type     | Description                                                                                                                                             |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iconLibrary`  | `string` | Icon library prefix                                                                                                                                     |
| `uno.base`     | `string` | Base (neutral) color                                                                                                                                    |
| `uno.primary`  | `string` | Primary (brand) color                                                                                                                                   |
| `uno.size`     | `string` | Base component size                                                                                                                                     |
| `uno.radius`   | `string` | Border radius                                                                                                                                           |
| `font.sans`    | `string` | Sans-serif font name                                                                                                                                    |
| `font.heading` | `string` | Heading font or `"inherit"`                                                                                                                             |
| `aliases`      | `object` | Import aliases per package (e.g. `ui`; future peripheral packages likewise) — each maps to an output dir via `tsconfig` paths (default `src/<package>`) |
| `registries`   | `object` | Additional registry namespace → URL mappings                                                                                                            |

## Project Structure

### Single Package

```
project/
├── src/
│   └── ui/           ← component output (uiDir)
│       ├── components/
│       ├── styles/
│       ├── theme/
│       ├── constants/
│       ├── resolver/
│       └── nuxt/
├── sbean.json
├── tsconfig.json
└── uno.config.ts
```

### Monorepo (pnpm workspaces)

```
project/
├── packages/
│   └── ui/           ← component output (uiDir)
│       ├── components/
│       ├── styles/
│       ├── theme/
│       ├── constants/
│       ├── resolver/
│       └── nuxt/
├── sbean.json
├── tsconfig.json
├── uno.config.ts
└── pnpm-workspace.yaml
```

## Alias System

SBean uses the `#ui` TypeScript path alias for all component imports:

```json
// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "#ui/*": ["./src/ui/*"]
    }
  }
}
```

All component imports use this namespace:

```ts
import { SButton } from '#ui/components/button';
import { buttonVariants } from '#ui/styles/button';
```

## Registry

Sbean fetches component source from the SoybeanUI registry at `https://ui.soybeanjs.cn/r/<package>/<component>.json` — the core `ui` package from `r/ui/{name}.json` (e.g. `r/ui/button.json`) and the catalog index from `r/registry.json`. Registry items are **namespaced by package**, so `{name}` in a registry URL template is the qualified item name (`ui/button`), not the bare component name. Core `ui` components can be referenced without a prefix (`sbean add button`); components from any future peripheral package will require the namespace prefix (`sbean add <package>/<component>`). A local cache (`~/.sbean/cache`) is maintained with 24-hour TTL and ETag support for efficient updates.

## Accordion

- Page URL: /components/accordion
- Markdown URL: /components/accordion.md
- Description: A vertically (or horizontally) stacked set of interactive headings that each reveal a section of content, supporting single or multiple expansion. SAccordion combines an AccordionRoot/AccordionItem/AccordionHeader/AccordionTrigger/AccordionContent/AccordionDescription family of headless primitives (zero styles) with the accordionVariants style recipe (8 slots, 6 sizes).

# Accordion

## Overview

A vertically (or horizontally) stacked set of interactive headings that each reveal a section of content, supporting single or multiple expansion. `SAccordion` combines an `AccordionRoot`/`AccordionItem`/`AccordionHeader`/`AccordionTrigger`/`AccordionContent`/`AccordionDescription` family of headless primitives (zero styles) with the `accordionVariants` style recipe (8 slots, 6 sizes).

Use it for FAQs, settings groups, collapsible navigation, or any "expand to reveal" pattern where one (or several) sections should be open at a time. Prefer `tabs` when only one panel should be visible at once and each panel has a persistent label, and `collapsible` for a single standalone foldable section.

`SAccordion` aggregates the primitives through `AccordionCompact` and is `items`-driven with `item`/`leading`/`title`/`trigger-icon`/`content` slots. For fully custom compositions, fall back to the headless `AccordionRoot`-family primitives.

## Usage

Usage examples for accordion are rendered on the site.

## Features

- 🧩 Headless/styled split — `AccordionCompact` aggregates the 6 primitives and is `items`-driven; `SAccordion` only injects styles and forwards slots/events
- 🎚️ Single / multiple — `multiple` toggles one-open vs many-open (`M extends boolean` generic); `collapsible` allows all sections closed
- ⌨️ Keyboard navigation — arrow keys move between triggers (`useArrowNavigation`), respecting `orientation` and `dir`; triggers expose `aria-expanded`/`aria-disabled`/`data-state`
- 🧭 Orientation — `vertical` (default) or `horizontal`
- ⛔ Disabled items — per-item `disabled` and root `disabled` propagation
- 🎨 6 sizes — xs–2xl `size` matching `ThemeSize`
- 🔧 Fully customizable — `as`/`asChild` on the trigger, `leading`/`title`/`trigger-icon`/`content`/`item` slots, and per-slot `ui` overrides
- ♿ Accessible by default — real `<button>` triggers with `aria-expanded`, collapsible animation via `data-state`, and `axe-core` zero violations

## Component family

- `SAccordion` (styled) — the entry wrapper; `accordionVariants` recipe with dynamic slot forwarding
- `AccordionRoot` (headless) — the state owner; `useSelection` manages single/multiple `modelValue`, exposes `dir`/`orientation`
- `AccordionItem` (headless) — one section; derives its open/disabled state from the root and wires arrow-key navigation
- `AccordionHeader` (headless) — the header container for the trigger
- `AccordionTrigger` (headless) — the `<button>` trigger; `aria-expanded`/`aria-disabled`/`data-state` and click-to-toggle
- `AccordionContent` (headless) — the animated collapsible content (`CollapsibleContent`)
- `AccordionDescription` (headless) — the default description text inside content
- `AccordionCompact` (headless) — the aggregated composite; iterates `items` into items and exposes the customization slots

## Demos

Interactive demos for accordion are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (8): Accordion, AccordionCompact, AccordionContent, AccordionDescription, AccordionHeader, AccordionItem, AccordionRoot, AccordionTrigger.

### Accordion

#### Props
Properties for the Accordion component.
- `class`: root class (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<AccordionUi>`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `itemProps`: Properties forwarded to the item element. (type `AccordionItemProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `AccordionHeaderProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `AccordionTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AccordionContentProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `AccordionDescriptionProps`; optional)
- `collapsible`: When type is "single", allows closing content when clicking trigger for an open item. When type is "multiple", this prop has no effect. (type `boolean`; default `false`; optional)
- `dir`: The reading direction of the accordion when applicable. If omitted, assumes LTR (left-to-right) reading mode. (type `Direction`; default `'ltr'`; optional)
- `disabled`: When `true`, prevents the user from interacting with the accordion and all its items (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the accordion. (type `DataOrientation`; default `'vertical'`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
#### Emits
Events for the Accordion component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
#### Slots
Slots for the Accordion component.
- `item`: Custom content for the item slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `content`: Custom content for the content slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)

### AccordionCompact

#### Props
Properties for the AccordionCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `itemProps`: Properties forwarded to the item element. (type `AccordionItemProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `AccordionHeaderProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `AccordionTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AccordionContentProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `AccordionDescriptionProps`; optional)
- `collapsible`: When type is "single", allows closing content when clicking trigger for an open item. When type is "multiple", this prop has no effect. (type `boolean`; default `false`; optional)
- `dir`: The reading direction of the accordion when applicable. If omitted, assumes LTR (left-to-right) reading mode. (type `Direction`; default `'ltr'`; optional)
- `disabled`: When `true`, prevents the user from interacting with the accordion and all its items (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the accordion. (type `DataOrientation`; default `'vertical'`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
#### Emits
Events for the AccordionCompact component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
#### Slots
Slots for the AccordionCompact component.
- `item`: Custom content for the item slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
- `content`: Custom content for the content slot. (type `((props: AccordionCompactSlotProps<T, M>) => any) | undefined`)
#### Slot Props
Slot properties for the AccordionCompact component.
- `item`: Current item data. (type `T`; required)
- `index`: Index of the current item. (type `number`; required)
- `modelValue`: Current model value. (type `(M extends true ? string[] : string) | undefined`; required)
- `open`: Whether the component is open. (type `boolean`; required)

### AccordionContent

#### Props
Properties for the AccordionContent component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AccordionDescription

- No documented props, emits, slots, or slot props were available.

### AccordionHeader

- No documented props, emits, slots, or slot props were available.

### AccordionItem

#### Props
Properties for the AccordionItem component.
- `value`: Value of the accordion item. All items within an accordion should use a unique value. (type `string`; required)
- `disabled`: When `true`, prevents the user from interacting with the collapsible. (type `boolean`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AccordionRoot

#### Props
Properties for the AccordionRoot component.
- `collapsible`: When type is "single", allows closing content when clicking trigger for an open item. When type is "multiple", this prop has no effect. (type `boolean`; default `false`; optional)
- `dir`: The reading direction of the accordion when applicable. If omitted, assumes LTR (left-to-right) reading mode. (type `Direction`; default `'ltr'`; optional)
- `disabled`: When `true`, prevents the user from interacting with the accordion and all its items (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the accordion. (type `DataOrientation`; default `'vertical'`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
#### Emits
Events for the AccordionRoot component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)

### AccordionTrigger

#### Props
Properties for the AccordionTrigger component.
- `disabledCollapsible`: When `true`, prevents the user from toggling the collapsible. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`AccordionCompact` owns the `items` iteration and default content assembly while every primitive stays style-free and only the UI wrapper injects the `accordionVariants` classes. This mirrors shadcn/ui's headless split and Radix's `Accordion` primitive, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a config-driven collapse with `defaultActiveKey`/`activeKey`. SoybeanUI's root uses `useSelection` so single/multiple modes share one state model, and arrow-key navigation is driven by the same `useArrowNavigation` composable used across the menu family for consistency.

| Capability                    | SoybeanUI | shadcn/ui | Ant Design Collapse | Element Plus Collapse | Mantine Accordion | Naive UI Collapse |
| :---------------------------- | :-------: | :-------: | :-----------------: | :-------------------: | :---------------: | :---------------: |
| Headless/styled split         |    ✅     |    ✅     |          —          |           —           |         —         |         —         |
| Single / multiple             |    ✅     |    ✅     |         ✅          |          ✅           |        ✅         |        ✅         |
| Collapsible (all closed)      |    ✅     |    ✅     |         ✅          |          ✅           |        ✅         |        ✅         |
| Keyboard arrow navigation     |    ✅     |    ✅     |         ✅          |          ✅           |        ✅         |        ✅         |
| Custom trigger icon           |    ✅     |     —     |         ✅          |          ✅           |        ✅         |        ✅         |
| Data-driven `items` (Compact) |    ✅     |     —     |         ✅          |          ✅           |        ✅         |        ✅         |
| Disabled item                 |    ✅     |    ✅     |         ✅          |          ✅           |        ✅         |        ✅         |
| Orientation (v/h)             |    ✅     |     —     |         ✅          |          ✅           |         —         |         —         |
| `as`/`asChild` trigger        |    ✅     |    ✅     |          —          |           —           |         —         |         —         |

`—` = unsupported or a different interaction model.

### Cautions

- In single mode (`multiple: false`) only one section stays open; with `collapsible` (default `true`) clicking the open trigger closes it, leaving all sections closed.
- Arrow-key navigation requires a trigger to be focused; the keys follow `orientation` (`ArrowUp`/`ArrowDown` vertically, `ArrowLeft`/`ArrowRight` horizontally) and swap under RTL via `dir`.
- `unmountOnHide` (default `true`) unmounts closed content; set it to `false` to keep it in the DOM (e.g. to preserve inner form state).
- The default trigger chevron rotates with CSS based on `data-state`; replace it via the `trigger-icon` slot if you need a different indicator.
- Disabled items ignore clicks and are skipped by arrow navigation but remain reachable in the DOM order for assistive tech.

### Roadmap

No blocking gaps identified for the core accordion API. A bordered `variant` set and a `left`-icon trigger layout are evaluated as enhancements tracked in `docs/roadmap.md`.

## FAQ

### How do I allow only one section open at a time?

Single mode is the default — bind `modelValue` to a single value:

```vue

```

### How do I allow multiple sections open?

Set `multiple` and bind an array:

```vue

```

### How do I let all sections be closed?

`collapsible` is `true` by default, so clicking the open trigger closes it:

```vue

```

### How do I customize the trigger icon?

Use the `trigger-icon` slot (or `leading` for a left icon):

```vue

  <template #trigger-icon="{ open }">
    <SIcon :icon="open ? 'lucide:minus' : 'lucide:plus'" />
  </template>

```

### How do I build a fully custom item?

Use the `item` slot to compose the headless parts yourself:

```vue

  <template #item="{ item, open }">
    <div class="border-b">
      <button type="button" :aria-expanded="open">{{ item.title }}</button>
      <div v-if="open">{{ item.description }}</div>
    </div>
  </template>

```

## Affix

- Page URL: /components/affix
- Markdown URL: /components/affix.md
- Description: Affix keeps content pinned to the top or bottom edge of the viewport or a custom scroll container while the target area is scrolling.

# Affix

## Overview

Affix keeps content pinned to the top or bottom edge of the viewport or a custom scroll container while the target area is scrolling.

> Note: In addition to SAffix, the headless layer also exports AffixCompact for the default placeholder/content structure, plus AffixRoot, AffixPlaceholder, AffixContent, and provideAffixUi for fully custom composition and style injection.

## Features

- **Pin to top or bottom** — `offsetTop` pins the content to the target's top edge once the placeholder scrolls past the threshold; `offsetBottom` pins it to the bottom edge. With neither set, the content affixes to the target's top at offset `0`.
- **Custom scroll target** — `target` accepts an `HTMLElement`, a CSS selector string, or `window` (default). Scroll, touch, resize, `load`, and `pageshow` events on the target trigger repositioning.
- **Placeholder preservation** — while affixed, a hidden placeholder (`role="presentation"`, `aria-hidden`) keeps the layout space so content below does not jump.
- **Reactive state** — `data-state="fixed|static"` on both root and content elements, plus a `change` event that fires only on state transitions (`true` when affixed, `false` when released).
- **Zero-size guard** — when the placeholder rect is all zeros (e.g. `display: none` or not yet rendered), positioning is skipped to avoid incorrectly fixing content.
- **Width & left preservation** — the fixed element keeps the placeholder's `width` and `left`, so layout and alignment are preserved across the transition.
- **rAF-throttled updates** — scroll/touch/resize handlers are coalesced through `useRafFn` (one measurement per frame), avoiding layout thrash during fast scrolling.
- **Dynamic target switching** — when the `target` prop changes, listeners are detached from the old target and attached to the new one via `onWatcherCleanup`.
- **Imperative API** — `AffixRoot` exposes `affixed` and `updatePosition()` via `defineExpose` for programmatic repositioning.
- **SSR safe** — `window` / `document` access is guarded (`getDefaultTarget` / `queryTargetSelector` / `measurePosition`); listeners activate client-side only.
- **Headless composition** — `AffixRoot` / `AffixPlaceholder` / `AffixContent` / `AffixCompact` are exported from `@soybeanjs/headless/affix` for fully custom styled builds.

## Usage

Usage examples for affix are rendered on the site.

## Demos

Interactive demos for affix are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Affix, AffixCompact, AffixContent, AffixPlaceholder, AffixRoot.

### Affix

#### Props
Properties for the Affix component.
- `class`: Additional class names to apply to the content element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<AffixUi>`; optional)
- `placeholderProps`: Properties forwarded to the placeholder element. (type `AffixPlaceholderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AffixContentProps`; optional)
- `offsetTop`: The offset from the top of the target container when the element becomes affixed. (type `number`; default `0`; optional)
- `offsetBottom`: The offset from the bottom of the target container when the element becomes affixed. (type `number`; optional)
- `target`: The element that Affix listens to for scroll position updates. (type `AffixTarget | null`; default `window`; optional)
#### Emits
Events for the Affix component.
- `change`: Emitted when change occurs. (type `[affixed: boolean]`; parameters `affixed: boolean`)

### AffixCompact

#### Props
Properties for the AffixCompact component.
- `placeholderProps`: Properties forwarded to the placeholder element. (type `AffixPlaceholderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AffixContentProps`; optional)
- `offsetTop`: The offset from the top of the target container when the element becomes affixed. (type `number`; default `0`; optional)
- `offsetBottom`: The offset from the bottom of the target container when the element becomes affixed. (type `number`; optional)
- `target`: The element that Affix listens to for scroll position updates. (type `AffixTarget | null`; default `window`; optional)
#### Emits
Events for the AffixCompact component.
- `change`: Emitted when change occurs. (type `[affixed: boolean]`; parameters `affixed: boolean`)

### AffixContent

- No documented props, emits, slots, or slot props were available.

### AffixPlaceholder

- No documented props, emits, slots, or slot props were available.

### AffixRoot

#### Props
Properties for the AffixRoot component.
- `offsetTop`: The offset from the top of the target container when the element becomes affixed. (type `number`; default `0`; optional)
- `offsetBottom`: The offset from the bottom of the target container when the element becomes affixed. (type `number`; optional)
- `target`: The element that Affix listens to for scroll position updates. (type `AffixTarget | null`; default `window`; optional)
#### Emits
Events for the AffixRoot component.
- `change`: Emitted when change occurs. (type `[affixed: boolean]`; parameters `affixed: boolean`)

## Notes

### Architecture and benchmark comparison

| Concern                      | SoybeanUI                                       | Ant Design `Affix`              | Element Plus `Affix`     |
| :--------------------------- | :---------------------------------------------- | :------------------------------ | :----------------------- |
| Headless / styled separation | ✅ `@soybeanjs/headless/affix` + `scv()` recipe | ❌ single styled package        | ❌ single styled package |
| Pin to top / bottom          | ✅ `offsetTop` / `offsetBottom`                 | ✅ `offsetTop` / `offsetBottom` | ✅ `offset`              |
| Custom target                | ✅ element / selector / window                  | ✅ `target` (function)          | ✅ `target` (function)   |
| Placeholder preservation     | ✅ hidden placeholder keeps space               | ✅ `placeholder` node           | ✅ `placeholder` node    |
| `change` event on transition | ✅ fires only on state change                   | ✅ `onChange`                   | ✅ `on-change`           |
| rAF-throttled measurement    | ✅ `useRafFn` frame coalescing                  | ✅ rAF loop                     | ✅ rAF loop              |
| Touch events                 | ✅ scroll + touchstart/move/end                 | ✅ touch support                | —                        |
| Dynamic target switching     | ✅ listener cleanup via `onWatcherCleanup`      | ✅ `updatePosition` re-init     | ✅ `update`              |
| Zero-size guard              | ✅ skips when rect is all zeros                 | —                               | —                        |
| Imperative API               | ✅ `affixed` + `updatePosition()`               | ✅ `updatePosition`             | —                        |
| SSR safety                   | ✅ guarded `window` / `document`                | partial                         | partial                  |

### Runtime considerations

1. **Offsets are relative to the target rect** — `top = offsetTop + targetRect.top`, `bottom = offsetBottom + (window.innerHeight - targetRect.bottom)`. Both can be combined; the last computed one wins when both thresholds pass.
2. **Zero-size guard** — `isZeroRect` skips positioning while the placeholder rect is all zeros (not rendered, `display: none`, or hidden), avoiding spurious fixing during SSR hydration or animation.
3. **Measurement is rAF-coalesced** — `useRafFn({ immediate: false, once: true })` runs `measurePosition` at most once per animation frame, so a burst of scroll events triggers a single layout read.
4. **Listener lifecycle** — the scroll/touch listeners bind to the resolved target when it changes (via `onWatcherCleanup`); `load` / `pageshow` / `resize` bind to `window`. All are removed on unmount.
5. **`internalOffsetTop`** — when neither `offsetTop` nor `offsetBottom` is provided, `offsetTop` defaults to `0`, so content affixes flush to the target's top edge.
6. **No-op when target is missing** — if the selector target cannot be resolved (or `window` is unavailable during SSR), `measurePosition` resets to static and waits for the next opportunity to resolve.

## FAQ

### When does the content become affixed?

The content affixes when the placeholder's top scrolls past `targetRect.top - offsetTop` (for top pinning) or the placeholder's bottom passes `targetRect.bottom + offsetBottom` (for bottom pinning). Once affixed, the element switches to `position: fixed` and a placeholder keeps its original space.

### How do I use a custom scroll container instead of the window?

Pass the scroll container to `target` — either a DOM element or a CSS selector string (e.g. `target="#scroll-container"`). Scroll and touch events on that container drive the measurement.

### Why does the element keep its width when fixed?

The fixed style copies `width` and `left` from the placeholder's rect so the affixed element stays visually aligned with where it would have been in flow. The placeholder retains `height` and `width` to prevent layout shift.

### Does the `change` event fire on every scroll?

No — `change` fires only when the affixed state actually transitions (`true` when fixing, `false` when releasing). Scrolling while already fixed emits nothing.

### Is the placeholder announced to screen readers?

No — the placeholder is `role="presentation"` and `aria-hidden="true"`, so it is invisible to assistive technology and only preserves layout space.

### How do I reposition programmatically?

`AffixRoot` exposes `affixed` and `updatePosition()`. Call `updatePosition()` after layout changes that the component cannot observe (e.g. content size changes inside the fixed element).

### Does it work with SSR?

Yes — all `window` / `document` access is guarded. On the server the affix simply renders static content; positioning activates client-side once the element and target exist.

## Headless Composition

When the default placeholder/content structure is enough, import `AffixCompact` from `@soybeanjs/headless/affix`. If you need separate control over the root, placeholder, and content elements, compose the headless primitives directly:

```vue
<script setup lang="ts">
import { computed } from 'vue';
import { AffixContent, AffixPlaceholder, AffixRoot, provideAffixUi } from '@soybeanjs/headless';

const ui = computed(() => ({
  content: 'data-[state=fixed]:z-50'
}));

provideAffixUi(ui);
</script>

<template>
  <AffixRoot :offset-top="24">
    <AffixPlaceholder />
    <AffixContent>
      <button type="button">Back to top</button>
    </AffixContent>
  </AffixRoot>
</template>
```

## Alert

- Page URL: /components/alert
- Markdown URL: /components/alert.md
- Description: A callout that surfaces important, time-sensitive information — warnings, errors, or confirmations — near the content it refers to. SAlert combines an AlertRoot/AlertTitle/AlertDescription/AlertClose family of headless primitives (zero styles) with the alertVariants style recipe (6 slots, 8 colors × 5 variants × 6 sizes).

# Alert

## Overview

A callout that surfaces important, time-sensitive information — warnings, errors, or confirmations — near the content it refers to. `SAlert` combines an `AlertRoot`/`AlertTitle`/`AlertDescription`/`AlertClose` family of headless primitives (zero styles) with the `alertVariants` style recipe (6 slots, 8 colors × 5 variants × 6 sizes).

Use it for inline feedback that must not be missed. Prefer `toast` for transient, global notifications and `dialog` for blocking confirmations. For a banner-style full-width variant, track the roadmap `Banner` item.

## Usage

Usage examples for alert are rendered on the site.

## Features

- 🧩 Headless/styled split — `AlertCompact` aggregates the primitives and composes the default icon/title/description/close; `SAlert` only injects styles and forwards slots/events
- 🏷️ Title + description — `title`/`description` props or the matching slots
- ❌ Closable — `closable` renders a close `<button>` (localized `aria-label`) driven by `v-model:open`
- 🎨 8 colors — `ThemeColor` values (`primary`/`destructive`/`success`/`warning`/`info`/`carbon`/`secondary`/`accent`)
- 🖌️ 5 variants — `solid`/`pure`/`outline`/`soft`/`ghost`
- 📐 6 sizes — xs–2xl `size`
- 🖼️ Leading icon — `icon` prop or the `leading` slot
- ♿ Accessible — the close control is a real `<button>` with a localized `aria-label`; `axe-core` reports zero violations

## Component family

- `SAlert` (styled) — the entry wrapper; `alertVariants` recipe with dynamic slot forwarding
- `AlertRoot` (headless) — the container; owns `open` via `useControllableState` and `provideAlertRootContext`
- `AlertContent` (headless) — the content area hosting title/description
- `AlertTitle` (headless) — the title
- `AlertDescription` (headless) — the description
- `AlertClose` (headless) — the close `<button>`; localized `aria-label`, emits `close` and toggles `open`
- `AlertCompact` (headless) — the aggregated composite; composes icon/title/description/close and exposes the slots

## Demos

Interactive demos for alert are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): Alert, AlertClose, AlertCompact, AlertContent, AlertDescription, AlertRoot, AlertTitle.

### Alert

#### Props
Properties for the Alert component.
- `class`: root class (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `variant`: Visual variant of the component. (type `AlertVariant`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<AlertUi>`; optional)
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `icon`: Icon rendered by the component. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)
- `closable`: Whether the component can be closed. (type `boolean`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AlertContentProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `AlertTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `AlertDescriptionProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `AlertCloseProps`; optional)
- `open`: The controlled open state of the alert. Can be bound with `v-model:open`. (type `boolean`; default `true`; optional)
- `role`: The ARIA live region role of the alert. `role="alert"` implies an assertive live region (interrupting), while `role="status"` implies a polite one (non-interrupting). (type `'alert' | 'status'`; default `'alert'`; optional)
#### Emits
Events for the Alert component.
- `update:open`: Emitted when the open changes. (type `[open: boolean]`; parameters `open: boolean`)
- `close`: Emitted when the close button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the Alert component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `title`: Custom content for the title slot. (type `(() => any) | undefined`)
- `description`: Custom content for the description slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `close`: Custom content for the close slot. (type `(() => any) | undefined`)

### AlertClose

#### Props
Properties for the AlertClose component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the AlertClose component.
- `close`: Emitted when the close button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### AlertCompact

#### Props
Properties for the AlertCompact component.
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `icon`: Icon rendered by the component. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)
- `closable`: Whether the component can be closed. (type `boolean`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AlertContentProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `AlertTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `AlertDescriptionProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `AlertCloseProps`; optional)
- `open`: The controlled open state of the alert. Can be bound with `v-model:open`. (type `boolean`; default `true`; optional)
- `role`: The ARIA live region role of the alert. `role="alert"` implies an assertive live region (interrupting), while `role="status"` implies a polite one (non-interrupting). (type `'alert' | 'status'`; default `'alert'`; optional)
#### Emits
Events for the AlertCompact component.
- `update:open`: Emitted when the open changes. (type `[open: boolean]`; parameters `open: boolean`)
- `close`: Emitted when the close button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the AlertCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `title`: Custom content for the title slot. (type `(() => any) | undefined`)
- `description`: Custom content for the description slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `close`: Custom content for the close slot. (type `(() => any) | undefined`)

### AlertContent

- No documented props, emits, slots, or slot props were available.

### AlertDescription

- No documented props, emits, slots, or slot props were available.

### AlertRoot

#### Props
Properties for the AlertRoot component.
- `open`: The controlled open state of the alert. Can be bound with `v-model:open`. (type `boolean`; default `true`; optional)
- `role`: The ARIA live region role of the alert. `role="alert"` implies an assertive live region (interrupting), while `role="status"` implies a polite one (non-interrupting). (type `'alert' | 'status'`; default `'alert'`; optional)
#### Emits
Events for the AlertRoot component.
- `update:open`: Emitted when the open changes. (type `[open: boolean]`; parameters `open: boolean`)

### AlertTitle

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`AlertCompact` owns the icon/title/description/close composition while every primitive stays style-free and only the UI wrapper injects the `alertVariants` classes. This mirrors shadcn/ui's headless/styled split, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled alert with `type`/`closable`/`showIcon` props. SoybeanUI exposes the full per-slot `*Props` channels and a `size` scale the single-package libraries generally omit, and localizes the close button's `aria-label` (via `alert.close`) instead of relying on a plain `×` glyph.

| Capability                  | SoybeanUI | shadcn/ui | Ant Design Alert | Element Plus Alert | Mantine Alert | Naive UI Alert |
| :-------------------------- | :-------: | :-------: | :--------------: | :----------------: | :-----------: | :------------: |
| Headless/styled split       |    ✅     |    ✅     |        —         |         —          |       —       |       —        |
| Title + description         |    ✅     |    ✅     |        ✅        |         ✅         |      ✅       |       ✅       |
| Closable                    |    ✅     |     —     |        ✅        |         ✅         |      ✅       |       ✅       |
| Leading icon                |    ✅     |     —     |        ✅        |         ✅         |      ✅       |       ✅       |
| Variants (solid/soft/ghost) |    ✅     |    ✅     |        —         |         —          |       —       |       —        |
| Colors (8)                  |    ✅     |    ✅     |        ✅        |         ✅         |      ✅       |       ✅       |
| Sizes (6)                   |    ✅     |     —     |        —         |         —          |       —       |       —        |
| Localized close label       |    ✅     |     —     |        —         |         ✅         |       —       |       —        |

`—` = unsupported or a different interaction model.

### Cautions

- The close button's `aria-label` is localized from `alert.close` (e.g. `Close alert`). Override it via `aria-label` on `SAlert` or a custom `close` slot.
- `open` defaults to `true`; `closable` shows the close button. Bind `open` with `v-model` to control dismissal.
- `variant="solid"` swaps text to the color's foreground; `soft`/`ghost` tint the background with a translucent color.
- The `icon` leading graphic is decorative; the title/description carry the message content.
- `Alert` is a static callout — it does not set a live/alert `role` or auto-dismiss; use `toast` for transient notifications.

### Roadmap

A full-width `Banner` variant is tracked in `docs/roadmap.md` (P2).

## FAQ

### How do I show a title and description?

Pass `title`/`description` props (or the matching slots):

```vue

```

### How do I make an alert closable?

Set `closable` and bind `open` with `v-model`:

```vue

```

### How do I change the color and variant?

Use `color` (8 values) and `variant` (`solid`/`pure`/`outline`/`soft`/`ghost`):

```vue

```

### How do I add an icon?

Use the `icon` prop (via ConfigProvider `iconRender`) or the `leading` slot:

```vue

```

### How do I customize the close control?

Use the `close` slot and read the close behavior from it (or provide your own `aria-label`):

```vue

  <template #close>
    <button type="button" aria-label="Dismiss" @click="open = false">×</button>
  </template>

```

## Anchor

- Page URL: /components/anchor
- Markdown URL: /components/anchor.md
- Description: Anchor provides in-page navigation for long content sections and keeps the current section highlighted while scrolling.

# Anchor

## Overview

Anchor provides in-page navigation for long content sections and keeps the current section highlighted while scrolling.

When the active item changes while scrolling, the hash in the address bar is also synchronized. Scroll-driven updates always use `history.replaceState` to avoid creating excessive history entries.

If the current URL already contains a hash on initial render, Anchor will scroll to the matching section after mount. When a custom scroll container becomes available later, Anchor will re-sync once that container is ready.

> `SAnchor` now delegates recursive item rendering to headless `AnchorCompact`. The same six `ui` slots are available from both `SAnchor` and `@soybeanjs/headless/anchor`.

## Features

- **Scroll-spy highlighting** — the root observes its scroll container (`window` by default or a custom element via `getContainer`) and marks the last section that crossed the `offsetTop + bounds` threshold as active, with `aria-current="location"` on the matching link.
- **Hash synchronization** — clicking a link writes the hash with `history.pushState` (or `history.replaceState` when `replace` is set); scroll-driven updates always `replaceState`; on mount the component scrolls to the hash that is already in the URL.
- **Smooth in-page scrolling** — clicking a hash link scrolls the container with `behavior: 'smooth'` and suspends scroll-spy re-sync until the animation settles (300 ms guard).
- **Custom scroll container** — `getContainer` returns any scrollable `HTMLElement`; anchor positions are measured relative to that container and re-synced when it replaces the initial `window` fallback.
- **Offset control** — `offsetTop` (default `0`) and `targetOffset` (takes precedence) shift the scroll destination so headings land below sticky headers; the value is also exposed as `--soybean-anchor-offset-top` for the sticky root.
- **Active detection tuning** — `bounds` (default `5`) is the pixel tolerance used to decide whether a section has been passed; `getCurrentAnchor` can remap the resolved href before it is emitted.
- **Recursive data-driven composition** — `SAnchor` renders nested `items` (arbitrary depth) through the generic headless `AnchorCompact`; each level wraps its own `AnchorLink`, indicator, title, and nested `sub` list.
- **Sticky rail** — `sticky` (default `true`) pins the anchor list to the top of the container with `top: var(--soybean-anchor-offset-top)` and caps its height to the viewport.
- **Per-item and global link props** — `disabled` and `target` can be set per item or globally via `linkProps`; an explicit item value always wins, and `linkProps.href` is intentionally excluded because the item's `href` owns the target.
- **Eight theme colors + six sizes** — `color` (primary…accent) and `size` (xs…2xl) variants from the `anchorVariants` `scv()` recipe, plus vertical / horizontal `orientation`.
- **Accessible by default** — the root renders a `<nav>` landmark with a localized `aria-label` (overridable), disabled links carry `aria-disabled` and leave the tab order, and the indicator is `aria-hidden`.
- **Headless composition** — `AnchorRoot` / `AnchorLink` / `AnchorCompact` / `AnchorItemCompact` are exported from `@soybeanjs/headless/anchor` for fully custom styled builds.

## Usage

Usage examples for anchor are rendered on the site.

> `SAnchor` now delegates recursive item rendering to headless `AnchorCompact`. For unstyled, data-driven usage, import `AnchorCompact` from `@soybeanjs/headless/anchor`.

## Demos

Interactive demos for anchor are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Anchor, AnchorCompact, AnchorItemCompact, AnchorLink, AnchorRoot.

### Anchor

#### Props
Properties for the Anchor component.
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<AnchorExtendedUi>`; optional)
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `sticky`: Whether sticky. (type `boolean`; optional)
- `items`: Items rendered by the component. (type `AnchorOptionData[]`; required)
- `linkProps`: Properties forwarded to the link element. (type `Omit<AnchorLinkProps, 'href'>`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `HTMLAttributes`; optional)
- `titleProps`: Properties forwarded to the title element. (type `HTMLAttributes`; optional)
- `subProps`: Properties forwarded to the sub element. (type `HTMLAttributes`; optional)
- `bounds`: Bounds. (type `number`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `getContainer`: Get container. (type `(() => AnchorContainer | null)`; optional)
- `getCurrentAnchor`: Get current anchor. (type `((activeHref: string) => string)`; optional)
- `modelValue`: Current model value. (type `string`; optional)
- `offsetTop`: Offset top. (type `number`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `replace`: Whether replace. (type `boolean`; optional)
- `targetOffset`: Target offset. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Anchor component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `activeChange`: Emitted when active change occurs. (type `[value: string]`; parameters `value: string`)
- `itemSelect`: Emitted when item select occurs. (type `[event: MouseEvent, payload: { href: string; }]`; parameters `event: MouseEvent, payload: { href: string; }`)

### AnchorCompact

#### Props
Properties for the AnchorCompact component.
- `items`: Items rendered by the component. (type `AnchorOptionData[]`; required)
- `linkProps`: Properties forwarded to the link element. (type `Omit<AnchorLinkProps, 'href'>`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `HTMLAttributes`; optional)
- `titleProps`: Properties forwarded to the title element. (type `HTMLAttributes`; optional)
- `subProps`: Properties forwarded to the sub element. (type `HTMLAttributes`; optional)
- `bounds`: Bounds. (type `number`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `getContainer`: Get container. (type `(() => AnchorContainer | null)`; optional)
- `getCurrentAnchor`: Get current anchor. (type `((activeHref: string) => string)`; optional)
- `modelValue`: Current model value. (type `string`; optional)
- `offsetTop`: Offset top. (type `number`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `replace`: Whether replace. (type `boolean`; optional)
- `targetOffset`: Target offset. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the AnchorCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `activeChange`: Emitted when active change occurs. (type `[value: string]`; parameters `value: string`)
- `itemSelect`: Emitted when item select occurs. (type `[event: MouseEvent, payload: { href: string; }]`; parameters `event: MouseEvent, payload: { href: string; }`)

### AnchorItemCompact

#### Props
Properties for the AnchorItemCompact component.
- `modelValue`: Current model value. (type `string`; optional)
- `item`: Current item data. (type `AnchorOptionData`; required)
- `linkProps`: Properties forwarded to the link element. (type `Omit<AnchorLinkProps, 'href'>`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `HTMLAttributes`; optional)
- `titleProps`: Properties forwarded to the title element. (type `HTMLAttributes`; optional)
- `subProps`: Properties forwarded to the sub element. (type `HTMLAttributes`; optional)

### AnchorLink

#### Props
Properties for the AnchorLink component.
- `href`: The link of anchor (type `string`; required)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AnchorRoot

#### Props
Properties for the AnchorRoot component.
- `bounds`: Bounds. (type `number`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `getContainer`: Get container. (type `(() => AnchorContainer | null)`; optional)
- `getCurrentAnchor`: Get current anchor. (type `((activeHref: string) => string)`; optional)
- `modelValue`: Current model value. (type `string`; optional)
- `offsetTop`: Offset top. (type `number`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `replace`: Whether replace. (type `boolean`; optional)
- `targetOffset`: Target offset. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the AnchorRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `activeChange`: Emitted when active change occurs. (type `[value: string]`; parameters `value: string`)
- `itemSelect`: Emitted when item select occurs. (type `[event: MouseEvent, payload: { href: string; }]`; parameters `event: MouseEvent, payload: { href: string; }`)

## Notes

### Architecture and benchmark comparison

| Concern                      | SoybeanUI                                                     | Ant Design `Anchor`             | Element Plus `Anchor` |
| :--------------------------- | :------------------------------------------------------------ | :------------------------------ | :-------------------- |
| Headless / styled separation | ✅ `@soybeanjs/headless/anchor` + `scv()`                     | ❌ single package               | ❌ single package     |
| Data-driven compact API      | ✅ generic `AnchorCompact` + recursive `items`                | ✅ `items`                      | ✅ `items`            |
| Scroll container             | ✅ `getContainer` (HTMLElement or window)                     | ✅ `getContainer`               | ✅ `container`        |
| Scroll offset                | ✅ `offsetTop` + `targetOffset`                               | ✅ `offsetTop` + `targetOffset` | ✅ `offset`           |
| Active bounds tolerance      | ✅ `bounds`                                                   | ✅ `bounds`                     | ✅ `bound`            |
| Active href transform        | ✅ `getCurrentAnchor`                                         | ✅ `getCurrentAnchor`           | —                     |
| Hash sync                    | ✅ pushState on click / replaceState on scroll                | ✅                              | ✅                    |
| Initial hash scroll          | ✅                                                            | ✅                              | —                     |
| Sticky rail                  | ✅ CSS `sticky` + offset var                                  | ✅ `affix` wrapper              | ✅ CSS sticky         |
| Nested items                 | ✅ recursive (arbitrary depth)                                | ❌ flat                         | ✅ 2 levels           |
| Disabled items               | ✅ per-item + `linkProps` fallback                            | ❌                              | ❌                    |
| Custom link props            | ✅ `linkProps` / `indicatorProps` / `titleProps` / `subProps` | —                               | —                     |
| Orientation                  | ✅ vertical / horizontal                                      | ❌ vertical only                | ✅ `direction`        |
| Theme colors / sizes         | ✅ 8 colors × 6 sizes                                         | ❌                              | ❌                    |
| Events                       | ✅ `activeChange` / `itemSelect`                              | ✅ `onChange` / `onClick`       | ✅ `change`           |

### Runtime considerations

1. **Measurement timing** — anchor positions are re-measured on every scroll event against the current scroll container. Sections that do not exist yet (or links not yet registered) are skipped, so the active item is only derived from registered links.
2. **Controlled vs. uncontrolled** — when `modelValue` is provided, internal writes only emit `update:modelValue`; the highlighted link follows the prop and no scrolling is triggered by external value changes.
3. **`getContainer` instability** — the component re-syncs whenever the container reference changes; returning a new element from every call causes repeated re-syncs, so memoize it when the element is created asynchronously.
4. **Hash-only links** — only links starting with `#` participate in scrolling and hash updates; plain/external hrefs are left to the browser's default navigation (and the `itemSelect` event still fires).
5. **Scroll-animation guard** — during the 300 ms after a programmatic scroll the scroll-spy is suspended so the intermediate positions do not flip the active item or rewrite the hash.
6. **Sticky rail** — `sticky` requires a scrollable ancestor for the rail to actually pin; the offset var keeps the rail below sticky headers. Set `sticky: false` for non-pinned usage.
7. **Disabled links** — a disabled item is inert: `aria-disabled="true"`, `tabindex="-1"`, and click/keyboard activation are blocked (no `itemSelect`). It stays registered so nested children can still be highlighted.

## FAQ

### How do I scroll an inner container instead of the window?

Pass `getContainer={() => myScrollableEl}`. Anchor positions are then measured relative to that element and scrolling is applied to it. When the element becomes available after mount, Anchor re-syncs automatically.

### How do I keep headings below a sticky header?

Set `offsetTop` to the header height. `SAnchor` scrolls to `elementTop - offsetTop` and exposes the same value as `--soybean-anchor-offset-top` so the sticky anchor rail also clears the header. Use `targetOffset` if the anchor offset must differ from the scroll offset.

### Why does the address bar update on scroll?

This is intentional — scroll-driven changes use `history.replaceState` so the URL hash always matches the section in view without flooding the history. Click-driven jumps use `pushState` unless you set `replace`.

### How is the active section chosen?

A section becomes active once its measured top is at or above `offsetTop + bounds`. Among the passed sections the one closest to the threshold (the most recently crossed) is highlighted. `bounds` increases the tolerance; `getCurrentAnchor` lets you remap the resolved value before it is emitted.

### Can I disable or customize individual links?

Yes — each item supports `disabled` and `target`; global defaults go through `linkProps`. Because the item's `href` always owns the destination, `linkProps.href` is not part of the type. `indicatorProps` / `titleProps` / `subProps` forward HTML attributes to the per-item elements.

### What does the nested composition look like?

Each item renders an `AnchorLink` (indicator + title) and, when it has `children`, a `sub` container that recursively renders `AnchorItemCompact` levels. The wrapper carries `data-soybean-anchor-item` with a `data-state` reflecting whether the item or any of its descendants is active.

## AppShell

- Page URL: /components/app-shell
- Markdown URL: /components/app-shell.md
- Description: An aggregated application shell that assembles the layout regions, menu, breadcrumb, page tabs, brand, and footer from props and slots.

# AppShell

## Overview

`SAppShell` is an aggregated application shell for admin-style applications. A single `mode`, one menu tree, and a handful of props assemble the whole shell: the layout regions (sidebar, header, tabs, content, footer) plus everything that fills them — navigation, breadcrumb, page tabs, brand, and footer.

Use it when an application needs a persistent shell around routed pages — a sidebar or top-bar navigation, a breadcrumb in the header, a page-tab strip, and a footer — without writing the wiring yourself. Prefer the primitives (`SLayout`, `SSplitNav`, `STreeMenu`, `STreeNav`, `SPageTabs`, `SBreadcrumb`) when the composition does not fit; the Layout Composition demo shows the same shell assembled by hand.

`SAppShell` is the aggregation layer of the layout family. It owns one thing the primitives cannot: the **mode skeleton** — which layout orientation, which menu renderer, which region each menu pane is mounted into, and the sidebar widths those panes require. Everything else stays in the family it belongs to: `SLayout` renders the regions, `SSplitNav` / `STreeMenu` / `STreeNav` render the menu, `SBreadcrumb` and `SPageTabs` render their own bars.

Like `SLayout`, the shell is router-agnostic: it takes a menu tree, breadcrumb items, and tab items as data and reports interactions back through events. Routing, permissions, tab collections, and cache policy stay in the host, and the [playground examples](#demos) show the wiring.

## Usage

Usage examples for app-shell are rendered on the site.

## Features

- 🧭 **Six modes** — `sidebar` (nested sidebar menu), `top` (popup top-bar menu), and the four `SSplitNav` modes `dual-vertical` / `vertical-horizontal` / `horizontal-vertical` / `horizontal-dual-vertical`, forwarded verbatim.
- 📐 **A sidebar that follows the menu** — the nested-pane modes size the sidebar to the panes they actually render: `rail + tree` while a first-level menu with children is active, the rail plus the folded pane or the rail alone otherwise.
- 🧩 **Renderer per mode** — one `items` tree feeds `STreeMenu`, `STreeNav`, or `SSplitNav`, chosen by the mode; `menuProps` / `menuUi` forward to the active renderer only.
- 🌲 **A menu that mirrors the route** — `expandStrategy` (default `selected`, or `keep`) drives the nested `STreeMenu` and the split panes: the active path stays expanded and the branches the session left behind close; `top` renders `STreeNav`, which has no expand strategy.
- 🪆 **Teleport mounting** — panes that belong in another region (a top bar beside a sidebar tree) are mounted into shell-owned targets; the shell generates the ids and exposes them on the `menu` slot.
- 🍞 **Breadcrumb from the menu** — the header breadcrumb is derived from `items` and the active value: the trail down to the active menu, where every ancestor whose menu has children opens a dropdown of those children, nested like the menu itself — an entry that has children keeps its own submenu. Pass `breadcrumbs` to render your own data instead.
- 📑 **Tabs and footer** — `tabs` render in the tab region and the footer is a slot; both accept per-region props and `ui` overrides.
- 🗂️ **A collapse that follows the panes** — a collapsed sidebar keeps its rail and folds the nested pane into its own icon rail, so the sidebar narrows to the columns it actually shows instead of leaving an expanded tree beside a shrunken rail; the trigger sits in the header, or in the sidebar's bottom corner for the modes whose first level is a top bar.
- 🏷️ **Brand is a slot** — the shell renders no logo of its own: inject the mark through `#logo` and the app name through `#title`. The shell places them so they line up with the menu: a single-column sidebar renders the region as one menu row (mark and title in it, folding to the item's icon width together with the menu), while a dual-vertical sidebar hands both to the menu's own top cells — the mark over the first-level rail, the title over the nested pane below it. `logoPlacement` moves the region to the top of the sidebar, its bottom, or the header.
- 📱 **Mobile drawer** — an unset `isMobile` follows the viewport, and the sidebar becomes the layout's dialog drawer. The shell renders the `sidebar` skeleton there whatever mode is bound, so the drawer holds the **full menu tree** — brand and one nested `STreeMenu` — and a top bar or a rail has nowhere to hide. The drawer always shows the expanded navigation: a collapse picked on desktop stays on desktop.
- 🎛️ **Three override levels** — `ui` for the shell's own nodes, `layoutUi` for the layout regions it themes, `menuUi` for the menu renderer; each region also accepts a slot.
- ♿ **Accessibility inherited** — keyboard, focus, ARIA, and RTL come from the composed families; the shell only adds structure and classes.

## Demos

Interactive demos for app-shell are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (3): AppShell, AppShellBrand, AppShellMenu.

### AppShell

#### Props
Properties for the AppShell component.
- `class`: Additional class names applied to the shell root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<UiClass<AppShellUiSlot>>`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; default `'md'`; optional)
- `mode`: Shell skeleton, driving both the layout regions and the menu shape. The **desktop** skeleton: in the mobile view the shell renders the `sidebar` one instead, so the drawer holds one nested tree holding the full menu. (type `AppShellMode`; default `'sidebar'`; optional)
- `side`: Side the sidebar is placed on. (type `import("@soybeanjs/headless").HorizontalSide`; default `'left'`; optional)
- `open`: The controlled expanded state of the sidebar. Can be bound with `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The expanded state of the sidebar when initially rendered. (type `boolean`; default `true`; optional)
- `mobileOpen`: The controlled open state of the mobile drawer. Can be bound with `v-model:mobileOpen`. The shell renders the drawer through `SLayout`, where the drawer is the mobile counterpart of the desktop sidebar and carries its own state. (type `boolean`; optional)
- `defaultMobileOpen`: The open state of the mobile drawer when it is initially rendered. (type `boolean`; default `false`; optional)
- `isMobile`: Whether the shell is in mobile view. When omitted, it is forwarded unset and `SLayout` resolves the mode: a viewport published by a host through `provideViewportContext`, then `useMediaQuery('(max-width: 767.9px)')`. Pass an explicit boolean to force it, e.g. for a server-side detection. (type `boolean`; optional)
- `layoutProps`: Properties forwarded to `SLayout`. Shell-owned options (`open`, `orientation`, `sidebarVisible`, `isMobile`, `pxToRem`) are derived from `mode`; `sidebarWidth` and `collapsedSidebarWidth` default to the widths the mode requires — override them only when the menu panes do not need to line up. (type `Omit<LayoutCompactProps, 'open' | 'defaultOpen' | 'class' | 'pxToRem' | 'mobileOpen' | 'defaultMobileOpen' | 'orienta...`; optional)
- `layoutUi`: Per-slot class overrides for the internal `SLayout`. Takes precedence over the shell's `layout*` UI slots. (type `Partial<LayoutUi>`; optional)
- `logoPlacement`: Placement of the brand region. `auto` follows the skeleton the shell renders; `sidebar` and `sidebar-bottom` need a skeleton whose sidebar is always a column of its own — see `AppShellLogoPlacement` for the modes that support the bottom placement. In the mobile view that skeleton is the `sidebar` one, so `auto` puts the brand in the drawer whatever mode is bound. (type `AppShellLogoPlacement`; default `'auto'`; optional)
- `expandStrategy`: The expand strategy of the rendered menu. - `keep`: keep the current expanded state; manually expanded or collapsed menus are not affected by activating other menus. The collapsible ancestors of the selected menu are expanded on mount and whenever the selected menu changes from outside (e.g. driven by an external route), so it stays visible. - `selected`: only expand the currently selected menu and all its ancestor menus; non-selected menus are collapsed when the selected menu changes. The shell defaults to `selected`: the navigation mirrors the current route, so one path stays expanded and the active entry keeps its place instead of competing with the branches opened earlier in the session. Applies to the single `STreeMenu` (`sidebar` mode) and to the nested vertical panes of `SSplitNav` (the split modes). `top` mode renders `STreeNav`, which has no expand strategy. `menuProps.tree` / `menuProps.split` take precedence over this prop. (type `TreeMenuExpandStrategy`; default `'selected'`; optional)
- `items`: Menu tree rendered by the shell. (type `AppShellMenuItem[]`; required)
- `modelValue`: The controlled active menu value. Can be bound with `v-model`. The active menu is controlled only: the shell derives the sidebar geometry and the breadcrumb from it before rendering, so it reads the value it is given rather than keeping one of its own. (type `string`; optional)
- `menuProps`: Properties forwarded to the rendered menu. (type `AppShellMenuProps`; optional)
- `menuUi`: Per-slot class overrides forwarded to the rendered menu. (type `AppShellMenuUi`; optional)
- `breadcrumbs`: Breadcrumb items rendered in the header. Omit it to derive the breadcrumb from `items` and the active value: the trail from the root menu down to the active item, where every ancestor whose menu has children opens a dropdown of those children — nested like the menu itself, so an entry that has children keeps its own submenu. Provide it to render a plain breadcrumb from your own data instead. (type `BreadcrumbOptionData[]`; optional)
- `breadcrumbVisible`: Whether the breadcrumb region renders when the trail is not empty. The region is hidden below the `md` breakpoint either way: a phone header keeps its trigger and its trailing actions. Bind `ui.breadcrumb` (e.g. `lt-md:flex`) to bring it back there. (type `boolean`; default `true`; optional)
- `breadcrumbProps`: Properties forwarded to `SBreadcrumb`. (type `Omit<BreadcrumbCompactProps<BreadcrumbOptionData>, 'items'>`; optional)
- `breadcrumbUi`: Per-slot class overrides for `SBreadcrumb`. (type `Partial<BreadcrumbUi>`; optional)
- `tabs`: Page tabs rendered in the tab region. (type `PageTabsOptionData[]`; optional)
- `tabValue`: The controlled active tab value. Can be bound with `v-model:tabValue`. (type `string`; optional)
- `tabProps`: Properties forwarded to `SPageTabs`. (type `Omit<PageTabsCompactProps<PageTabsOptionData>, 'modelValue' | 'defaultValue' | 'items'>`; optional)
- `tabUi`: Per-slot class overrides for `SPageTabs`. (type `Partial<PageTabsUi>`; optional)
- `triggerVisible`: Whether the sidebar trigger renders in the header. (type `boolean`; default `true`; optional)
#### Emits
Events for the AppShell component.
- `update:open`: Emitted when the sidebar expanded state changes. (type `[open: boolean]`; parameters `open: boolean`)
- `update:mobileOpen`: Emitted when the mobile drawer open state changes. (type `[open: boolean]`; parameters `open: boolean`)
- `update:modelValue`: Emitted when the active menu value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when a menu leaf is selected. (type `[key: string, event?: Event | undefined]`; parameters `key: string, event?: Event | undefined`)
- `open`: Emitted when a menu parent opens its nested pane. (type `[item: AppShellMenuItem, event?: Event | undefined]`; parameters `item: AppShellMenuItem, event?: Event | undefined`)
- `update:tabValue`: Emitted when the active tab changes. (type `[value: string]`; parameters `value: string`)
- `update:tabs`: Emitted when the tab collection changes (close, pin, drag reorder). (type `[tabs: PageTabsOptionData[]]`; parameters `tabs: PageTabsOptionData[]`)
- `tabClick`: Emitted when a tab is clicked. (type `[tab: PageTabsOptionData]`; parameters `tab: PageTabsOptionData`)
- `tabClose`: Emitted when a tab is closed. (type `[tab: PageTabsOptionData]`; parameters `tab: PageTabsOptionData`)
- `tabPin`: Emitted when a tab is pinned or unpinned. (type `[tab: PageTabsOptionData]`; parameters `tab: PageTabsOptionData`)
- `tabContextmenu`: Emitted when the tab context menu target changes. (type `[tab: PageTabsOptionData]`; parameters `tab: PageTabsOptionData`)
- `tabSelectContextMenu`: Emitted when a tab context menu item is selected. (type `[menu: PageTabsContextMenuOptionData, tab: PageTabsOptionData]`; parameters `menu: PageTabsContextMenuOptionData, tab: PageTabsOptionData`)
- `tabDragStart`: Emitted when dragging a tab starts. (type `[tab: PageTabsDragEvent<PageTabsOptionData>]`; parameters `tab: PageTabsDragEvent<PageTabsOptionData>`)
- `tabDragMove`: Emitted while a tab is being dragged. (type `[tab: PageTabsDragEvent<PageTabsOptionData>]`; parameters `tab: PageTabsDragEvent<PageTabsOptionData>`)
- `tabDragReorder`: Emitted when the dragged tab is reordered in place. (type `[tab: PageTabsDragEvent<PageTabsOptionData>]`; parameters `tab: PageTabsDragEvent<PageTabsOptionData>`)
- `tabDragEnd`: Emitted when dragging a tab ends. (type `[tab: PageTabsDragEvent<PageTabsOptionData>]`; parameters `tab: PageTabsDragEvent<PageTabsOptionData>`)
- `breadcrumbClick`: Emitted when a breadcrumb item is clicked. (type `[item: BreadcrumbOptionData]`; parameters `item: BreadcrumbOptionData`)
#### Slots
Slots for the AppShell component.
- `default`: Custom content for the default slot — the page content. (type `(() => any) | undefined`)
- `logo`: Custom content for the brand mark. The shell renders it in a cell of its own so the brand lines up with the menu: over the first-level rail of the rail modes, and centered while the sidebar is collapsed. In the sidebar placement of the dual-vertical shapes that cell is the menu's own `top-left` one, so the rail's divider runs through the mark instead of the shell drawing a second one; every other placement renders the region beside the menu. The region renders as soon as this slot is provided; `title` is optional. (type `((props: AppShellBrandSlotProps) => any) | undefined`)
- `title`: Custom content for the brand title. Rendered next to the mark, and aligned to the sidebar's second (nested pane) column in the rail modes — through the menu's own `top-right` cell in the dual-vertical shapes. It is hidden while the sidebar is collapsed — the column it aligns to is folded away — and in placements that have no pane column to align to. (type `((props: AppShellBrandSlotProps) => any) | undefined`)
- `sidebar-start`: Custom content rendered at the top of the sidebar. (type `(() => any) | undefined`)
- `sidebar-end`: Custom content rendered at the bottom of the sidebar. (type `(() => any) | undefined`)
- `menu`: Custom content for the menu. Replaces the menu instance, not the mount targets. (type `((props: AppShellMenuSlotProps) => any) | undefined`)
- `header-start`: Custom content for the header leading region. (type `(() => any) | undefined`)
- `header`: Custom content for the header center region. (type `(() => any) | undefined`)
- `header-end`: Custom content for the header trailing region. (type `(() => any) | undefined`)
- `breadcrumb`: Custom content for the breadcrumb region. (type `((props: { items: BreadcrumbOptionData[]; }) => any) | undefined`)
- `tabs`: Custom content for the tab region. (type `(() => any) | undefined`)
- `footer`: Custom content for the footer region. (type `(() => any) | undefined`)

### AppShellBrand

#### Slot Props
Slot properties of the brand slots.
- `collapsed`: Whether the sidebar is collapsed. (type `boolean`; required)
- `placement`: Region the brand is rendered in. (type `'header' | 'sidebar' | 'sidebar-bottom'`; required)

### AppShellMenu

#### Props
Per-renderer props forwarded by the shell to the menu it renders.
- `tree`: Forwarded to the nested `STreeMenu` (`sidebar` mode). (type `Omit<TreeMenuCompactProps<import("@soybeanjs/headless").TreeMenuBaseOptionData>, 'modelValue' | 'defaultValue' | 'ite...`; optional)
- `split`: Forwarded to `SSplitNav` (the four split modes). (type `Omit<SplitNavRootProps<SplitNavBaseOptionData>, 'modelValue' | 'defaultValue' | 'as' | 'class' | 'items' | 'collapsed...`; optional)
- `treeNav`: Forwarded to `STreeNav` (`top` mode). (type `Omit<TreeNavCompactProps, 'modelValue' | 'defaultValue' | 'class' | 'items'>`; optional)
#### Slot Props
Slot properties of the menu slot.
- `mode`: Shell mode the menu renders for. The mode the host bound, reported as-is: the shell renders the `sidebar` skeleton in the mobile view whatever this says. (type `'sidebar' | 'top' | SplitNavMode`; required)
- `collapsed`: Whether the sidebar is collapsed. (type `boolean`; required)
- `collapsedWidth`: Collapsed width of the sidebar, in pixels. (type `number`; required)
- `side`: Side the sidebar is placed on. (type `'right' | 'left'`; required)
- `headerMountId`: Id of the header element the horizontal pane mounts into, when the mode teleports it. (type `string | undefined`; required)
- `sidebarMountId`: Id of the sidebar element the vertical pane mounts into, when the mode teleports it. (type `string | undefined`; required)

## Notes

### Mode skeleton

`mode` drives the layout orientation, the menu renderer, and where the menu panes mount. Mode names describe the **menu shape**, not the layout orientation — the orientation follows from whether the first menu level is vertical or horizontal.

| `mode`                     | First level | Renderer    | `layoutProps.orientation` | Brand   | Collapse trigger | Menu panes                                            |
| :------------------------- | :---------- | :---------- | :------------------------ | :------ | :--------------- | :---------------------------------------------------- |
| `sidebar`                  | sidebar     | `STreeMenu` | `horizontal`              | sidebar | header           | one nested tree                                       |
| `top`                      | header      | `STreeNav`  | `vertical`                | header  | —                | one nav bar, collapsible via `menuProps.treeNav`      |
| `dual-vertical`            | sidebar     | `SSplitNav` | `horizontal`              | sidebar | header           | rail + nested tree, side by side                      |
| `vertical-horizontal`      | sidebar     | `SSplitNav` | `horizontal`              | header  | header           | rail in the sidebar, horizontal sub-nav in the header |
| `horizontal-vertical`      | header      | `SSplitNav` | `vertical`                | header  | sidebar bottom   | top bar in the header, tree in the sidebar            |
| `horizontal-dual-vertical` | header      | `SSplitNav` | `vertical`                | header  | sidebar bottom   | top bar in the header, rail + tree in the sidebar     |

The table describes the desktop view. On a phone the shell renders the `sidebar` skeleton for every mode — see [Mobile view](#mobile-view).

The collapse trigger lives where the mode's first level is: the top-bar-first modes (`horizontal-vertical`, `horizontal-dual-vertical`) keep it in the bottom corner of the sidebar — right-aligned over the column it collapses, centered over that column's icon rail once the sidebar is folded — because their header already carries the first level; every other sidebar mode keeps it beside the brand in the header. `triggerVisible` hides it either way.

The two sidebar placements render the trigger only while that pane column exists: a sidebar left with nothing but a rail has nothing to collapse, so opening a branch from the top bar is what brings the trigger out. The row it sits in mirrors the columns as well — its first cell is the rail's width and carries the same divider the pane column leads with, so the line runs on past the menu to the sidebar's bottom edge.

The nested panes only take space while they have something to show, and the shell asks the split-nav family which columns exist instead of guessing per mode: the sidebar of `dual-vertical` is the rail plus the tree while a first-level menu with children is active, and the rail alone otherwise; `horizontal-vertical` has no rail, so its sidebar is the tree or nothing at all. `horizontal-dual-vertical` is the one to read twice: its sidebar hosts the dual-vertical pane of the active **first-level** menu, so the rail holds that menu's children and the pane the level below them — activating a first-level leaf, or opening a menu whose children have not been opened yet, leaves the sidebar with the rail alone or with no column at all. A sidebar left with no column takes and paints nothing: it reports the column as out of flow (`data-sidebar-flow="false"` on the layout root), which collapses the sidebar-adjacent spacing the `floating`/`inset` variants add and hides the empty column, while the region itself stays in the tree — it hosts the mount targets the panes teleport into, and the menu root that owns the top bar. The pane follows every menu activation rather than the value: activating a parent opens it, activating a leaf closes it, and re-activating the leaf that is already active closes it too — that activation resets the menu's path without moving `v-model`. Collapsing the sidebar folds the pane with it: the sidebar becomes the rail plus the pane's icon rail (or that icon rail alone in the rail-less mode), and the entries below the pane's own top level stay reachable from the popups the collapsed menu opens.

The rule behind the orientation column: a vertical first level keeps the sidebar full height and lets the header start beside it (`orientation="horizontal"`); a horizontal first level puts the header across the full width with the sidebar beneath it (`orientation="vertical"`). This is the inverse of the raw `SLayout` prop names, so read this table rather than guessing.

### Mobile view

On a phone the sidebar is the layout's drawer, and a drawer is a single column: a top bar, a rail, or a pane has nowhere to go in it. So the shell renders the **`sidebar` skeleton** there for every mode — brand on top, one nested `STreeMenu` under it holding the full menu tree, opened from the header trigger. The other regions stay where they are, and the tabs, content, and footer are untouched. A `top` mode therefore still has navigation on a phone: its bar moves into the drawer instead of unfolding across a header that cannot hold it.

The header gives up the breadcrumb there. A trail beside the trigger and the trailing actions has no room on a phone, and it outranks both: it would take its own content width and push the actions outside the viewport — the page with it. So the crumb is hidden below the `md` breakpoint, which is the same `767.9px` the shell switches views on. It is a styled rule, not a rendered one: the region is still in the markup on a phone, invisible, so the first paint on a server-rendered page never shows the trail either. Pass `ui.breadcrumb` (e.g. `lt-md:flex`) to bring it back, or `breadcrumbVisible` to drop it everywhere.

On a header that does have room, a deep trail **truncates** instead of wrapping or pushing: the crumb region is the only part of the leading region that shrinks, its items stay on one line, and each label is ellipsized — the trailing actions keep their share whatever the trail length.

The `mode` prop is never overwritten: it describes the desktop shape, `data-mode` keeps reporting what you bound, and the `menu` slot keeps receiving it. Leaving the mobile view is all it takes to get that shape back.

The shell resolves the view the same way `SLayout` does — the explicit `isMobile` prop, a viewport published by a host through `provideViewportContext`, then `useMediaQuery` over the shared `767.9px` breakpoint — so the two can never disagree about which view they are in. Force the shape from the outside the same way the shell does: bind `isMobile`, or publish a viewport through `provideViewportContext` for a device preview.

Two consequences follow from rendering the `sidebar` skeleton. The brand follows it — `logoPlacement="auto"` puts the region in the drawer even in the modes whose desktop default is the header — and a custom `#menu` slot is rendered as-is: replacing the menu means owning the phone shape too, since the drawer is a single column.

### Brand placement

`#logo` and `#title` render in one region; `logoPlacement` decides where that region goes, and the mode decides what it can line up with. The sidebar placements mirror the columns the menu renders — the mark takes the first column, the title the second — so the brand sits exactly over the rail and the pane below it instead of being padded to the sidebar. In the `dual-vertical` shapes those two cells are the menu's own: the shell passes the mark to its `top-left` and the title to its `top-right`, so the pane column's leading divider runs through the brand band instead of the shell drawing a line of its own.

| `mode`                     | Default placement | `sidebar` | `sidebar-bottom` | What the region lines up with                                        |
| :------------------------- | :---------------- | :-------: | :--------------: | :------------------------------------------------------------------- |
| `sidebar`                  | sidebar           |    ✅     |        ✅        | One column: mark and title share a row, centered while collapsed.    |
| `top`                      | header            |    ❌     |        ❌        | No sidebar region; both fall back to the header.                     |
| `dual-vertical`            | sidebar           |    ✅     |        ✅        | The menu's `top-left` cell on the rail, its `top-right` on the pane. |
| `vertical-horizontal`      | header            |    ⚠️     |        ❌        | The sidebar is the rail alone, so only the mark renders there.       |
| `horizontal-vertical`      | header            |    ⚠️     |        ❌        | The sidebar is the pane of the active first-level menu.              |
| `horizontal-dual-vertical` | header            |    ⚠️     |        ❌        | The sidebar hosts the columns of the active first-level menu.        |

❌ means the shell keeps the mode's default placement rather than rendering the region where it cannot stay. ⚠️ means the placement is honored, but those sidebars only have columns while the active first-level menu has children — the brand comes and goes with the menu, which is why `sidebar-bottom` is refused there: a brand pinned to a column that keeps disappearing reads as a bug, while one in the header never moves.

In the mobile view the shell renders the `sidebar` skeleton, so `auto` puts the region in the drawer whatever mode is bound — see [Mobile view](#mobile-view).

Three rules hold in every placement: a bottom region renders after the menu and `sidebar-end`, so it sits on the sidebar's bottom edge; the title is hidden while the sidebar is collapsed, because the pane column it aligns to is folded away; and the mark either centers in the shrunken sidebar (`sidebar`) or stays on the rail that keeps its column (the dual-vertical shapes, where it is the menu's `top-left` cell).

The divider belongs to the column that follows: `SSplitNav` leads the pane with it, so it spans that column's whole height — the brand band above the items included — and the collapse-trigger row continues it to the sidebar's bottom edge. The shell adds no brand-cell divider of its own, and a sidebar that shows the rail alone has no inner divider at all. The columns themselves stretch to the sidebar's full height for the same reason — a divider that stops where the items do looks like a mistake.

### Architecture and benchmark comparison

| Concern           | SoybeanUI `SAppShell`                                                                  | Ant Design Pro `ProLayout`               | Element Plus          | shadcn/ui                 |
| :---------------- | :------------------------------------------------------------------------------------- | :--------------------------------------- | :-------------------- | :------------------------ |
| Layer split       | Styled aggregation over the headless `layout` family; `SLayout` still ships standalone | Single styled package                    | Single styled package | Copy-in block, no library |
| Modes             | 6 (`sidebar`, `top`, + 4 split shapes) driven by one `mode`                            | 6 (`side`/`top`/`mix` + header variants) | —                     | 1                         |
| Menu tree         | One `items` tree, rendered by `STreeMenu` / `STreeNav` / `SSplitNav` per mode          | Routes/props                             | `el-menu` config      | Composed by hand          |
| Sidebar geometry  | Derived from `mode` + `size`, aligned to the menu panes                                | Numeric props                            | Numeric props         | Hand-written CSS          |
| Brand             | `#logo` / `#title` slots, aligned to the menu columns                                  | `logo` / `title` props                   | `el-aside` content    | Composed by hand          |
| Breadcrumb / tabs | `breadcrumbs` / `tabs` data props, rendered by `SBreadcrumb` / `SPageTabs`             | `menu` config + `PageContainer`          | Composed by hand      | Composed by hand          |
| Router dependency | None — data in, events out                                                             | Vue Router assumed                       | None                  | None                      |
| Overrides         | `ui` / `layoutUi` / `menuUi` + a slot per region                                       | `token` / slots                          | CSS vars              | Edit the copied source    |
| Accessibility     | Owned by the composed headless families                                                | Package-level                            | Package-level         | Manual                    |

### Cautions

1. **The brand is yours.** There is no `logo` or `title` prop: the mark goes in `#logo`, the app name and any subtitle in `#title`. The shell renders the region and hands both slots the live `collapsed` state and the resolved `placement` so the injected content can adapt. `#title` is optional — it is hidden while the sidebar is collapsed, since the column it aligns to is folded away — and a brand without `#logo` renders no region at all. Where the sidebar is a single column, the region itself renders as a tree-menu item row: it takes the menu root's inset and folds to the item's icon width with the menu, which is what keeps the mark in the menu's icon column after collapsing — and it centers the mark there, since the folded row is icon-only and its own padding would otherwise leave a mark wider than the content box against the row's trailing edge. In the dual-vertical shapes the mark and the title are injected into the menu's `top-left` / `top-right` cells instead, so the divider belongs to the menu; in the header and bottom placements the region keeps its own cells. The row itself is not interactive — inject your own link or trigger inside the slot when the brand has to navigate.
2. **`isMobile` defaults to the viewport, on both layers.** The shell resolves the view for the skeleton it renders — the explicit `isMobile` prop, a viewport published by a host through `provideViewportContext`, or `useMediaQuery(mobileViewportQuery)` (the `767.9px` breakpoint the styled sidebar hides at) — while the raw prop is what reaches `SLayout`, still unset, so the layout keeps its `lt-md` first-paint fallback. Pass an explicit boolean (e.g. a server-side hint) to override both at once. See [Mobile view](#mobile-view).
3. **Sidebar widths are derived — do not override them casually.** `layoutProps.sidebarWidth` / `collapsedSidebarWidth` win over the derived values, but in the split modes that breaks the alignment between the sidebar and the menu panes, and it also loses the dynamic behaviour below.
4. **Switching modes re-creates the menu.** Each mode renders a different menu instance, so the panes' expanded state (which lives inside `SSplitNav` / `STreeMenu`) resets to the active path on a mode change — and on the switch between the desktop and mobile shapes, which replaces the renderer just as well.
5. **The top bar is a `STreeNav`, not a plain menubar.** It selects through `modelValue` like the sidebar: activating a leaf emits `select` / `update:modelValue`, an entry with children only opens its popup, and an entry that carries `to` / `href` follows it as well. Set `menuProps.treeNav.collapsible` to fold the entries that no longer fit into a trailing "more" popup.
6. **The tab collection is mutated in place.** `SPageTabs` removes a closed tab and flips `pinned` by mutating the `tabs` array it is given; `update:tabs` only fires for bulk operations (close others/all) and drag reorders. Keep the collection reactive (a deep `ref`, not `shallowRef`) and use `tabClose` / `tabPin` when you need to observe those actions.
7. **A collapsed sidebar folds the nested pane with it.** The rail keeps its width, the pane collapses to its icon rail, and the sidebar takes exactly those columns — nothing overlays the content. The folded menu keeps its own behaviour: leaves show tooltips and branches open their flyout popup, so the hierarchy stays reachable at every level. A menu tree that has to stay readable at a glance should keep the sidebar open and let the pane take a column. The collapse trigger follows the same skeleton: the top-bar-first modes keep it in the sidebar's bottom corner — and only while the pane column is there to collapse — right-aligned over the pane and centered over that column once it folds, while every other mode keeps it in the header.
8. **Sidebar content sits outside a landmark.** The layout sidebar region is a plain element with no landmark role, so content injected around the menu (brand, `sidebar-start`, `sidebar-end`) is not inside a landmark. Wrap it in your own landmark if you run an accessibility audit.
9. **The active menu is controlled — there is no initial-value prop.** The shell derives its sidebar geometry and breadcrumb from the value before it renders, so it reads the value it is given instead of keeping one of its own. Bind `v-model` (or pass `modelValue` and handle `update:modelValue`): with no value the shell shows no active menu, an empty breadcrumb, and a sidebar with none of its pane columns.
10. **The menu expands along the route by default.** `expandStrategy` defaults to `selected`: only the chain the active menu sits in stays expanded, so a branch you opened and then navigated away from closes instead of piling up in the pane. Pass `expand-strategy="keep"` when manual expansions have to survive navigation, or set it per renderer through `menuProps.tree` / `menuProps.split` when only one of them should differ — those take precedence over the shell prop. The `top` mode renders `STreeNav`, which has no expand strategy, so the prop never reaches its markup.
11. **The brand follows the columns, and only two modes can pin it to the bottom.** In the sidebar placements the mark takes the first column the menu renders and the title the second — through the menu's own `top-left` / `top-right` cells in the dual-vertical shapes, through a region of the shell's own everywhere else — so they line up with the rail and the pane below them; a column that does not exist drops its cell, which is why the title is hidden whenever the sidebar shows no pane (nothing opened yet, or collapsed). `sidebar-bottom` additionally needs a sidebar that is always a column of its own — `sidebar` and `dual-vertical` support it, every other mode keeps its default placement instead of pinning the brand where it would come and go with the menu. See [Brand placement](#brand-placement).

## FAQ

### How do I keep the breadcrumb in sync with the route?

Keep `v-model` in sync with the route and the breadcrumb follows on its own: it is derived from `items` plus the active value, so the trail, the labels, and the dropdowns all come from one menu tree. It renders in the header where that header has room for it, and is hidden on a phone — see [Mobile view](#mobile-view). When the trail has to differ from the menu — permission-trimmed routes, a title that is not the menu label — pass your own `breadcrumbs` and the shell renders that data instead. `breadcrumbClick` reports crumb activation, while picking an entry in an ancestor dropdown behaves exactly like that entry in the menu: one with children opens its own submenu, and a leaf emits `select` / `update:modelValue`.

### Why does the sidebar change width when I open another menu?

Because the nested pane is part of the sidebar only while it exists. A first-level menu without children has no pane to show, so the sidebar falls back to its rail; activating a menu with children widens it again. A sidebar left with no column at all — a rail-less mode such as `horizontal-vertical` on a first-level leaf — takes and paints nothing instead of keeping an empty column. The collapsed sidebar follows the same rule with the pane folded: the rail plus the pane's icon rail, or the rail alone when there is nothing to show. Overriding `layoutProps.sidebarWidth` gives a constant width and loses that behaviour.

### Why does the branch I opened close when I navigate?

Because the menu follows the route by default. `expandStrategy` is `selected`, so the expanded set is replaced by the chain the active menu sits in as soon as the selection changes: the pane stays aligned with the current page instead of accumulating the branches of a long session. Pass `expand-strategy="keep"` to let a branch you opened by hand survive navigation:

```vue

```

Either way the chain of the active menu is expanded on mount and whenever the value moves from outside — a route change driving `v-model`, for example — so the current page never goes out of sight. The strategy reaches the nested `STreeMenu` (`sidebar` mode) and the split panes; `top` mode renders a `STreeNav` with no branches to expand, so it has no effect there.

### How do I pin the brand to the bottom of the sidebar?

Set `logo-placement="sidebar-bottom"` in a mode that supports it (`sidebar` or `dual-vertical`). The region renders after the menu and after `sidebar-end`, and the menu region grows to fill the sidebar, so the brand lands on the bottom edge:

```vue

```

Everything else about the brand stays the same: the mark and the title still line up with the columns above them, the title still hides when the sidebar is collapsed, and the mark still centers in the shrunken sidebar — or stays on the rail in `dual-vertical`. The other modes keep their default placement, which the [Brand placement](#brand-placement) table spells out per mode.

### Why does the brand title disappear?

Because the title's cell is a sidebar column like any other: it takes the width of the nested pane, and the pane column only exists while a first-level menu with children is open and the sidebar is expanded. With nothing opened yet, or with the sidebar collapsed (the pane folds into its icon rail), there is no column for the title to align to, so the shell stops rendering it instead of reserving width the sidebar does not take — the title cell of `SSplitNav` simply never receives content. The mark always stays — it aligns to the first-level rail, which is the column that survives.

### How do I make the sidebar narrower or wider?

Set `layoutProps.sidebarWidth` / `collapsedSidebarWidth` for the `sidebar` mode. In the split modes leave them alone: the widths are computed from the pane metrics of the active `size`, and overriding them desynchronises the sidebar from the menu.

### How do I open or close the mobile drawer?

Bind `v-model:mobileOpen` (`default-mobile-open` when uncontrolled). On mobile the layout replaces the desktop sidebar with a drawer, so the drawer carries its own state next to `open`: `open` / `v-model:open` keeps controlling the desktop collapse, and the shell's trigger toggles whichever state the current mode renders. One binding cannot serve both — the desktop sidebar starts expanded while the drawer has to start closed.

### How do I keep the top bar in sync with the route?

The same way as the sidebar: keep `v-model` in sync and the bar highlights the active entry, including through nested levels — an ancestor whose child is active is marked as well. Entries with `to` / `href` navigate as well as report, so a routed app can either let the router drive `v-model` or rely on the activation the shell reports.

### How do I add a page header or a footer above the tabs?

The `#header` slot replaces the header's center region (the `#header-start` / `#header-end` slots cover the leading and trailing regions), and the `#footer` slot fills the footer. For a page-level header inside the content, compose `SCard` or a plain header in the default slot — there is no page-header region in the shell.

### How do I replace the menu entirely?

Use the `#menu` slot. It replaces the menu instance, not the mount targets: the shell still renders the region and the teleport targets, and the slot receives `headerMountId` / `sidebarMountId` so your own `SSplitNav` can target them.

## AspectRatio

- Page URL: /components/aspect-ratio
- Markdown URL: /components/aspect-ratio.md
- Description: SAspectRatio maintains a fixed aspect ratio for its content using the CSS padding-bottom technique. It wraps content in a relatively-positioned container with a dynamic paddingBottom percentage, and an absolutely-positioned inner element that fills the container. Use it to prevent layout shift when loading images, videos, or embeds with known dimensions.

# AspectRatio

## Overview

`SAspectRatio` maintains a fixed aspect ratio for its content using the CSS padding-bottom technique. It wraps content in a relatively-positioned container with a dynamic `paddingBottom` percentage, and an absolutely-positioned inner element that fills the container. Use it to prevent layout shift when loading images, videos, or embeds with known dimensions.

## Usage

Usage examples for aspect-ratio are rendered on the site.

## Features

- 📐 **Aspect ratio control** — Pass any numeric `ratio` (e.g., `16/9`, `4/3`, `1`); the component computes the correct padding percentage.
- 🔧 **Polymorphic rendering** — The `as` prop lets you render the inner content element as any HTML tag or component (defaults to `div`).
- 📊 **Slot scope** — The default slot receives `aspect` (the computed padding percentage) for advanced use cases.
- 🎨 **Class forwarding** — `class` and other attrs are forwarded to the inner content element, not the wrapper.
- ♿ **Accessible** — The wrapper is a plain `<div>`; accessibility depends on the slotted content (e.g., `<img alt="...">`).
- 🌐 **SSR-safe** — Pure computed values, no browser APIs.

## Demos

Interactive demos for aspect-ratio are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): AspectRatio.

### AspectRatio

#### Props
Properties for the AspectRatio component.
- `ratio`: The desired ratio. Eg: 16/9 (type `number`; default `1`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture

`SAspectRatio` is a headless primitive — the UI layer re-exports the headless component directly. It uses the padding-bottom aspect-ratio technique: a wrapper `<div>` with `position: relative; width: 100%` and `paddingBottom: (1/ratio) * 100%`, and an inner element (via `Primitive`) with `position: absolute; inset: 0` that fills the wrapper. The inner element's `paddingBottom` is reactive — changing `ratio` updates the layout instantly.

The inline positioning styles (`position: relative`, `position: absolute; inset: 0`) are structural — they are essential to the padding-bottom technique and are not decorative. This matches the Radix UI / shadcn-ui AspectRatio implementation.

### Benchmark differences

| Aspect       | SoybeanUI                 | shadcn/ui `AspectRatio`   | MUI `AspectRatio`         | Ant Design |
| :----------- | :------------------------ | :------------------------ | :------------------------ | :--------- |
| Architecture | headless + UI re-export   | headless + styled         | styled only               | —          |
| Technique    | padding-bottom + absolute | padding-bottom + absolute | padding-bottom + absolute | —          |
| Polymorphic  | `as` prop via `Primitive` | —                         | —                         | —          |
| Slot scope   | `aspect` percentage       | —                         | —                         | —          |
| Ratio input  | `number` (e.g., `16/9`)   | `number` (e.g., `16/9`)   | `ratio` (e.g., `16/9`)    | —          |

### FAQ

**How do I use a 16:9 ratio?**
Pass `:ratio="16/9"` (note the `:` for Vue expression binding): `<SAspectRatio :ratio="16/9">...</SAspectRatio>`.

**Can I render the inner element as something other than a div?**
Yes. Use the `as` prop: `<SAspectRatio as="section">...</SAspectRatio>` renders the inner element as a `<section>`.

**Why are there inline styles in the headless layer?**
The `position: relative` on the wrapper and `position: absolute; inset: 0` on the inner element are structural — they are required for the padding-bottom technique to work. Without them, the aspect ratio cannot be maintained. This is an accepted deviation from the "no styles in headless" rule, consistent with Radix UI and shadcn/ui.

**What is the `aspect` slot prop?**
The default slot receives `aspect` — the computed padding percentage (e.g., `56.25` for 16:9). You can use it for debugging or custom layout logic: `<SAspectRatio v-slot="{ aspect }">...</SAspectRatio>`.

## Autocomplete

- Page URL: /components/autocomplete
- Markdown URL: /components/autocomplete.md
- Description: An autocomplete that filters suggestion items from text input and quickly fills the input with a selected result. It opens as you type, fuzzy-matches options with Fuse, and supports grouping, a clearable input, and a data-driven compact API. Use it when users should type keywords to get suggestions over free text; when options come from a fixed list, prefer SSelect; when options come from a known set that benefits from type-to-filter, SCombobox is the closer sibling.

# Autocomplete

## Overview

An autocomplete that filters suggestion items from text input and quickly fills the input with a selected result. It opens as you type, fuzzy-matches options with Fuse, and supports grouping, a clearable input, and a data-driven compact API. Use it when users should type keywords to get suggestions over free text; when options come from a fixed list, prefer `SSelect`; when options come from a known set that benefits from type-to-filter, `SCombobox` is the closer sibling.

## Usage

Usage examples for autocomplete are rendered on the site.

## Features

- 🔍 Type-to-open filtering backed by Fuse fuzzy search (`threshold: 0.3`, matching `label` / `value` / `keywords` / `groupLabel`)
- ⌨️ Full keyboard navigation — ArrowDown/Up/Home/End open and move, Enter/Space select, typeahead, Escape close
- 🗂 Grouping with group labels, separators, and empty states (no-match / no-data)
- 🧹 Clearable input (`clearable` → `clearLabel` / `resetModelValueOnClear`)
- 🎛 `openOnFocus` / `openOnClick` dual open strategy with controlled `v-model:open`
- 📊 Data-driven `AutocompleteCompact` API — `items` (options use `label` / `value` fields) + grouping
- ♿ WAI-ARIA combobox pattern — `role="combobox"` / `listbox` / `option`, `aria-activedescendant`, axe-clean when open
- 🎨 17 recipe slots and 7 size variants via `autocompleteVariants`

## Demos

Interactive demos for autocomplete are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (14): Autocomplete, AutocompleteAnchor, AutocompleteCompact, AutocompleteContent, AutocompleteGroup, AutocompleteGroupLabel, AutocompleteInput, AutocompleteItem, AutocompleteItemIndicator, AutocompletePortal, AutocompleteRoot, AutocompleteSeparator, AutocompleteTrigger, AutocompleteViewport.

### Autocomplete

#### Props
Properties for the Autocomplete component.
- `class`: Root class. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<AutocompleteUi>`; optional)
- `modelValue`: The controlled value of the autocomplete input. (type `string`; optional)
- `defaultValue`: The initial value of the autocomplete input. (type `string`; optional)
- `items`: Items rendered by the component. (type `AutocompleteOptionData<T>[]`; required)
- `placeholder`: Placeholder. (type `string`; optional)
- `clearable`: Whether clearable. (type `boolean`; optional)
- `clearLabel`: Clear label. (type `string`; optional)
- `emptyLabel`: Empty label. (type `string`; optional)
- `fuseOptions`: Fuse options. (type `UseFuseOptions<AutocompleteSearchOptionData>`; optional)
- `anchorProps`: Properties forwarded to the anchor element. (type `AutocompleteAnchorProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `AutocompleteInputProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `AutocompleteTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `AutocompletePortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AutocompleteContentProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `AutocompleteViewportProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `AutocompleteGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `AutocompleteGroupLabelProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `Omit<AutocompleteItemProps, 'disabled' | 'value'>`; optional)
- `itemIndicatorProps`: Properties forwarded to the item indicator element. (type `AutocompleteItemIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `AutocompleteSeparatorProps`; optional)
- `open`: The controlled open state of the autocomplete popup. (type `boolean`; optional)
- `defaultOpen`: The open state of the autocomplete popup when initially rendered. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with autocomplete. (type `boolean`; optional)
- `dir`: The reading direction of the autocomplete when applicable. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight. (type `boolean`; optional)
- `openOnFocus`: Whether to open the autocomplete when the input is focused. (type `boolean`; optional)
- `openOnClick`: Whether to open the autocomplete when the input is clicked. (type `boolean`; optional)
- `resetModelValueOnClear`: When `true`, clearing the search term also resets `modelValue` to an empty string. (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Autocomplete component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:open`: Emitted when the open state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `highlight`: Emitted when highlight occurs. (type `[payload?: AutocompleteHighlightPayload | undefined]`; parameters `payload?: AutocompleteHighlightPayload | undefined`)
- `select`: Emitted when select occurs. (type `[item: T]`; parameters `item: T`)
#### Slots
Slots for the Autocomplete component.
- `input-leading`: Custom content for the input leading slot. (type `(() => any) | undefined`)
- `input-trailing`: Custom content for the input trailing slot. (type `(() => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `(() => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: { item: AutocompleteGroupOptionData<T> | Extract<T, { items: T[]; }>; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-text`: Custom content for the item text slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-indicator`: Custom content for the item indicator slot. (type `((props: { item: T; }) => any) | undefined`)

### AutocompleteAnchor

#### Props
Properties for the AutocompleteAnchor component.
- `reference`: No description. (type `ReferenceElement`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AutocompleteCompact

#### Props
Properties for the AutocompleteCompact component.
- `modelValue`: The controlled value of the autocomplete input. (type `string`; optional)
- `defaultValue`: The initial value of the autocomplete input. (type `string`; optional)
- `items`: Items rendered by the component. (type `AutocompleteOptionData<T>[]`; required)
- `placeholder`: Placeholder. (type `string`; optional)
- `clearable`: Whether clearable. (type `boolean`; optional)
- `clearLabel`: Clear label. (type `string`; optional)
- `emptyLabel`: Empty label. (type `string`; optional)
- `fuseOptions`: Fuse options. (type `UseFuseOptions<AutocompleteSearchOptionData>`; optional)
- `anchorProps`: Properties forwarded to the anchor element. (type `AutocompleteAnchorProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `AutocompleteInputProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `AutocompleteTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `AutocompletePortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `AutocompleteContentProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `AutocompleteViewportProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `AutocompleteGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `AutocompleteGroupLabelProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `Omit<AutocompleteItemProps, 'disabled' | 'value'>`; optional)
- `itemIndicatorProps`: Properties forwarded to the item indicator element. (type `AutocompleteItemIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `AutocompleteSeparatorProps`; optional)
- `open`: The controlled open state of the autocomplete popup. (type `boolean`; optional)
- `defaultOpen`: The open state of the autocomplete popup when initially rendered. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with autocomplete. (type `boolean`; optional)
- `dir`: The reading direction of the autocomplete when applicable. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight. (type `boolean`; optional)
- `openOnFocus`: Whether to open the autocomplete when the input is focused. (type `boolean`; optional)
- `openOnClick`: Whether to open the autocomplete when the input is clicked. (type `boolean`; optional)
- `resetModelValueOnClear`: When `true`, clearing the search term also resets `modelValue` to an empty string. (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the AutocompleteCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:open`: Emitted when the open state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `highlight`: Emitted when highlight occurs. (type `[payload?: AutocompleteHighlightPayload | undefined]`; parameters `payload?: AutocompleteHighlightPayload | undefined`)
- `select`: Emitted when select occurs. (type `[item: T]`; parameters `item: T`)
#### Slots
Slots for the AutocompleteCompact component.
- `input-leading`: Custom content for the input leading slot. (type `(() => any) | undefined`)
- `input-trailing`: Custom content for the input trailing slot. (type `(() => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `(() => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: { item: Extract<AutocompleteOptionData<T>, { items: T[]; }>; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-text`: Custom content for the item text slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-indicator`: Custom content for the item indicator slot. (type `((props: { item: T; }) => any) | undefined`)

### AutocompleteContent

#### Props
Properties for the AutocompleteContent component.
- `position`: Position. (type `'inline' | 'popper'`; optional)
- `bodyLock`: Whether body lock. (type `boolean`; optional)
- `hideWhenEmpty`: Whether hide when empty. (type `boolean`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopperPositioningPopupProps`; optional)
- `open`: Whether the floating layer is open. Drives the positioning lifecycle (`isPositioned` resets when open flips); the positioning primitive itself has no open state, so consumers wire their own open state here. (type `boolean`; default `true`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the anchor to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the anchor. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the anchor. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `false`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the anchor is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the anchor becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: When `true`, focus cannot escape the content via keyboard, pointer, or a programmatic focus. (type `boolean`; default `false`; optional)
- `disableOutsidePointerEvents`: When `true`, hover/focus/click interactions will be disabled on elements outside the `DismissableLayer`. Users will need to click twice on outside elements to interact with them: once to close the `DismissableLayer`, and again to trigger the element. (type `boolean`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the AutocompleteContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: Event handler called when the positioner is placed (type `[]`)

### AutocompleteGroup

- No documented props, emits, slots, or slot props were available.

### AutocompleteGroupLabel

- No documented props, emits, slots, or slot props were available.

### AutocompleteInput

#### Props
Properties for the AutocompleteInput component.
- `inputRef`: Input ref. (type `((el: HTMLInputElement) => void)`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputControlProps`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)

### AutocompleteItem

#### Props
Properties for the AutocompleteItem component.
- `textValue`: Text value. (type `string`; optional)
- `value`: The value given as data when submitted with a `name`. (type `string`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the AutocompleteItem component.
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)

### AutocompleteItemIndicator

#### Props
Properties for the AutocompleteItemIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AutocompletePortal

- No documented props, emits, slots, or slot props were available.

### AutocompleteRoot

#### Props
Properties for the AutocompleteRoot component.
- `modelValue`: The controlled value of the autocomplete input. (type `string`; optional)
- `defaultValue`: The value of the autocomplete input when initially rendered. (type `string`; optional)
- `open`: The controlled open state of the autocomplete popup. (type `boolean`; optional)
- `defaultOpen`: The open state of the autocomplete popup when initially rendered. (type `boolean`; optional)
- `dir`: The reading direction of the autocomplete when applicable. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with autocomplete. (type `boolean`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight. (type `boolean`; optional)
- `openOnFocus`: Whether to open the autocomplete when the input is focused. (type `boolean`; optional)
- `openOnClick`: Whether to open the autocomplete when the input is clicked. (type `boolean`; optional)
- `resetModelValueOnClear`: When `true`, clearing the search term also resets `modelValue` to an empty string. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the AutocompleteRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:open`: Emitted when the open state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `highlight`: Emitted when highlight occurs. (type `[payload?: AutocompleteHighlightPayload | undefined]`; parameters `payload?: AutocompleteHighlightPayload | undefined`)

### AutocompleteSeparator

#### Props
Properties for the AutocompleteSeparator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AutocompleteTrigger

#### Props
Properties for the AutocompleteTrigger component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### AutocompleteViewport

#### Props
Properties for the AutocompleteViewport component.
- `nonce`: Nonce. (type `string`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI builds autocomplete by reusing the combobox component family (Anchor/Content/Item/Viewport/Trigger/Empty/Cancel) over the listbox base plus Popper positioning. `AutocompleteRoot` disables combobox's built-in filtering (`ignoreFilter`) and delegates matching to the compact layer's `useFuse`, so autocomplete and combobox share the same interaction kernel and differ only in filter and display strategy. The `scv()` recipe `autocompleteVariants` declares 17 slots and 7 size variants.

| Capability                    | SoybeanUI | reka-ui `Combobox` | Algolia Autocomplete | Ant Design `AutoComplete` |
| :---------------------------- | :-------: | :----------------: | :------------------: | :-----------------------: |
| headless/styled split         |    ✅     |         ✅         |          —           |             —             |
| Type-to-filter + fuzzy match  |    ✅     |         —          |          ✅          |            ✅             |
| combobox/listbox roles        |    ✅     |         ✅         |          ✅          |            ✅             |
| Keyboard nav + typeahead      |    ✅     |         ✅         |          ✅          |            ✅             |
| Grouping + group labels       |    ✅     |         ✅         |          —           |             —             |
| `openOnFocus` / `openOnClick` |    ✅     |         —          |          ✅          |            ✅             |
| Clear button + empty state    |    ✅     |         ✅         |          —           |            ✅             |
| Data-driven Compact API       |    ✅     |         —          |          —           |             —             |
| axe-clean (open state)        |    ✅     |         —          |          —           |             —             |

### Cautions

- Filtering happens client-side with Fuse; for remote suggestions, pass pre-filtered `items` or debounce the input yourself.
- The popup stays open when focus moves to the clear button (the blur-enclosure check covers the whole anchor area) and closes only when focus leaves the component — this was a fixed regression, so do not restore trigger-only containment.
- When the root is `disabled`, every item is unselectable, including items that declare their own `disabled` (unified `rootDisabled || item.disabled` guard).
- The viewport (`role="listbox"`) exposes a localized `aria-label` by default; override it via `viewportProps['aria-label']`.

## FAQ

### How do I show suggestions without typing?

Use `openOnFocus` to open the popup when the input receives focus, and `openOnClick` to open when the input is clicked.

### How do I tune how fuzzy the matching is?

Pass `fuseOptions` to tune the Fuse search — for example, raise `threshold` for looser matches or use `keys` to restrict which fields participate.

### What is the difference between `SAutocomplete`, `SCombobox`, and `SSelect`?

`SAutocomplete` fuzzy-matches suggestions over free text (Fuse); `SCombobox` type-to-filters a known option list; `SSelect` is trigger-driven with typeahead only and no text input.

### How do I clear the input and reset the model value?

Pass `clearable`. `resetModelValueOnClear` decides whether clearing also emits an empty `modelValue` or only resets the search term.

## Avatar

- Page URL: /components/avatar
- Markdown URL: /components/avatar.md
- Description: An image element with a fallback for representing the user. SAvatar combines a AvatarRoot/AvatarImage/AvatarFallback family of headless primitives (zero styles) with the avatarVariants style recipe (3 slots: root/image/fallback, 6 sizes xs–2xl).

# Avatar

## Overview

An image element with a fallback for representing the user. `SAvatar` combines a `AvatarRoot`/`AvatarImage`/`AvatarFallback` family of headless primitives (zero styles) with the `avatarVariants` style recipe (3 slots: root/image/fallback, 6 sizes xs–2xl).

Use it for user profiles, team/participant lists, or any spot that needs an identity image that degrades gracefully when the picture is slow, missing, or fails to load. Prefer `image` or `icon` for static or decorative imagery that has no identity fallback; prefer `skeleton` when you want to reserve space before content arrives.

`SAvatar` aggregates the primitives through `AvatarCompact` and exposes a `src`-driven API with `fallback-label` and `delay-ms`. For fully custom compositions, fall back to the headless `AvatarRoot`/`AvatarImage`/`AvatarFallback` primitives.

## Usage

Usage examples for avatar are rendered on the site.

## Features

- 🧩 Headless/styled split — `AvatarCompact` aggregates `AvatarRoot`/`AvatarImage`/`AvatarFallback` and exposes `image`/`fallback` slots; `SAvatar` only injects styles and forwards slots/events
- 🖼️ Graceful loading — the image is shown only once it has actually loaded; while loading or on error the fallback text/slot is rendered instead
- 🎭 Fallback slot — a custom `fallback` slot replaces the text label for initials, icons, or any VNode
- ⏱️ Delay control — `delay-ms` defers the fallback so it only appears for slower connections
- 🎨 6 sizes — xs–2xl sizing with `size` matching the shared `ThemeSize` scale
- ♿ Accessible by default — the loaded image inherits the fallback label as its accessible name, and the default fallback text is rendered as real content; `axe-core` reports zero violations
- 🧩 Fully customizable — per-slot `ui` overrides, root `class` override, and `image`/`fallback` slots replacing the defaults

## Component family

- `SAvatar` (styled) — the entry wrapper; `avatarVariants` recipe with dynamic slot forwarding
- `AvatarRoot` (headless) — the container; owns the shared image-loading state via `provideAvatarRootContext`
- `AvatarImage` (headless) — the `<img>`; tracked through `useImageLoadingStatus` and hidden until loaded
- `AvatarFallback` (headless) — the fallback content; rendered only when the image is not loaded (and after `delay-ms`)
- `AvatarCompact` (headless) — the aggregated composite; composes root/image/fallback and defaults the image `alt` to `fallback-label`

## Demos

Interactive demos for avatar are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Avatar, AvatarCompact, AvatarFallback, AvatarImage, AvatarRoot.

### Avatar

#### Props
Properties for the Avatar component.
- `class`: root class (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<AvatarUi>`; optional)
- `src`: The image source URL. (type `string`; required)
- `delayMs`: Useful for delaying fallback rendering so it only appears for those with slower connections. (type `number`; default `undefined`; optional)
- `fallbackLabel`: Fallback text rendered when no custom fallback slot is provided. (type `string`; optional)
- `imageProps`: Properties forwarded to the image element. (type `AvatarImageProps`; optional)
- `fallbackProps`: Properties forwarded to the fallback element. (type `AvatarFallbackProps`; optional)
#### Emits
Events for the Avatar component.
- `loadingStatusChange`: Event handler called when the image loading status changes. This is useful for controlling what to render as the image is loading. (type `[status: ImageLoadingStatus]`; parameters `status: ImageLoadingStatus`)

### AvatarCompact

#### Props
Properties for the AvatarCompact component.
- `src`: The image source URL. (type `string`; required)
- `delayMs`: Useful for delaying fallback rendering so it only appears for those with slower connections. (type `number`; default `undefined`; optional)
- `fallbackLabel`: Fallback text rendered when no custom fallback slot is provided. (type `string`; optional)
- `imageProps`: Properties forwarded to the image element. (type `AvatarImageProps`; optional)
- `fallbackProps`: Properties forwarded to the fallback element. (type `AvatarFallbackProps`; optional)
#### Emits
Events for the AvatarCompact component.
- `loadingStatusChange`: Event handler called when the image loading status changes. This is useful for controlling what to render as the image is loading. (type `[status: ImageLoadingStatus]`; parameters `status: ImageLoadingStatus`)
#### Slots
Slots for the AvatarCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `image`: Custom content for the image slot. (type `(() => any) | undefined`)
- `fallback`: Custom content for the fallback slot. (type `(() => any) | undefined`)

### AvatarFallback

#### Props
Properties for the AvatarFallback component.
- `delayMs`: Useful for delaying rendering so it only appears for those with slower connections. (type `number`; default `undefined`; optional)

### AvatarImage

#### Props
Properties for the AvatarImage component.
- `src`: The image source URL (type `string`; required)
- `alt`: Alternate text for the image. When unset the avatar's fallback label is used so the loaded image keeps an accessible name; set to `''` to mark a purely decorative avatar. (type `string`; default `undefined`; optional)
- `referrerpolicy`: The referrer policy for the image (type `('' | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-...`; optional)
- `crossorigin`: The cross-origin setting for the image (type `'' | 'anonymous' | 'use-credentials'`; optional)
#### Emits
Events for the AvatarImage component.
- `loadingStatusChange`: Event handler called when the image loading status changes. This is useful for controlling what to render as the image is loading. (type `[status: ImageLoadingStatus]`; parameters `status: ImageLoadingStatus`)

### AvatarRoot

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`AvatarCompact` owns the load-state orchestration (which part shows when) while every primitive stays style-free and only the UI wrapper injects the `avatarVariants` classes. This mirrors shadcn/ui's `Avatar`/`AvatarImage`/`AvatarFallback` headless trio and Radix's `Avatar` primitive, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled `Avatar` component with an `alt`/`src` prop. SoybeanUI deliberately routes the fallback text and image `alt` through the aggregate (`fallback-label`), so the loaded image keeps an accessible name without forcing consumers to repeat it.

| Capability                    | SoybeanUI | shadcn/ui | Ant Design Avatar | Element Plus Avatar | Mantine Avatar | Naive UI Avatar |
| :---------------------------- | :-------: | :-------: | :---------------: | :-----------------: | :------------: | :-------------: |
| Headless/styled split         |    ✅     |    ✅     |         —         |          —          |       —        |        —        |
| Image + fallback text/slot    |    ✅     |    ✅     |        ✅         |         ✅          |       ✅       |       ✅        |
| Fallback delay (`delay-ms`)   |    ✅     |    ✅     |         —         |          —          |       —        |        —        |
| Accessible name auto-derived  |    ✅     |     —     |         —         |          —          |       —        |        —        |
| Composite with per-part props |    ✅     |    ✅     |         —         |          —          |       —        |        —        |
| Configurable size (ThemeSize) |    ✅     |   class   |        ✅         |         ✅          |       ✅       |       ✅        |

`—` = unsupported or a different interaction model (AntD/Element Plus/Mantine/Naive UI ship a single styled component; shadcn/ui leaves the image `alt` to the consumer and provides no fallback delay).

### Cautions

- The image is only rendered (and its `alt` exposed) after it loads; before that the fallback is the visible content. Do not rely on the image element existing in the DOM before the load event.
- When the image fails, `loadingStatusChange` emits `'error'` and the fallback stays visible. Listen to this event to drive logging or retries.
- A `fallback-label` is used both as the fallback text and as the loaded image's accessible name. Set `imageProps.alt` to `''` if the avatar is purely decorative and should be skipped by assistive technology.
- `delay-ms` only delays the _fallback_; the image still starts loading immediately, so a fast network still prefers the picture.
- The root is a `<span>` (not a `<button>`/link), so it is not focusable or interactive by default — wrap it in a link/button when it should be clickable.

## FAQ

### How do I show initials when the image has not loaded yet?

Pass `fallback-label` (or the `fallback` slot) — it renders while the image is loading or after a failure:

```vue

```

### How do I delay the fallback for slow connections?

Use `:delay-ms`; the fallback only appears after the given milliseconds have elapsed without the image loading:

```vue

```

### How do I use an icon instead of text as the fallback?

Use the `fallback` slot to render any content:

```vue

  <template #fallback><SIcon icon="lucide:user" /></template>

```

### How do I react to a failed image load?

Listen to `@loading-status-change`; it emits `'loading'` / `'loaded'` / `'error'`:

```vue

```

### How do I make a purely decorative avatar?

Set `imageProps.alt` to `''` so assistive technology skips it:

```vue

```

## Backtop

- Page URL: /components/backtop
- Markdown URL: /components/backtop.md
- Description: SBacktop reveals a floating button after the scroll target passes a configurable threshold and smoothly scrolls that target back to the top when activated. It wraps SButton with scroll-position tracking, requestAnimationFrame-based smooth scrolling, and prefers-reduced-motion support. Use it to let users quickly return to the top of long pages or scrollable containers.

# Backtop

## Overview

`SBacktop` reveals a floating button after the scroll target passes a configurable threshold and smoothly scrolls that target back to the top when activated. It wraps `SButton` with scroll-position tracking, `requestAnimationFrame`-based smooth scrolling, and `prefers-reduced-motion` support. Use it to let users quickly return to the top of long pages or scrollable containers.

> Note: In addition to `SBacktop`, the headless layer also exports `Backtop` for custom composition.

## Usage

Usage examples for backtop are rendered on the site.

## Features

- 📏 **Visibility threshold** — The button appears only after scrolling past `visibilityHeight` pixels (default `400`).
- 🎬 **Smooth animation** — Scrolls to top with an `easeInOutCubic` easing over `duration` ms (default `300`). Set `duration={0}` for instant scroll.
- ♿ **Reduced motion** — Respects `prefers-reduced-motion: reduce`; skips animation and scrolls instantly when the user prefers reduced motion.
- 🎯 **Flexible target** — `target` accepts `window` (default), an `HTMLElement`, a `Ref<HTMLElement>`, or a CSS selector string.
- 🔧 **Headless composition** — The headless `Backtop` is exported separately for custom button styling; `SBacktop` provides preset `buttonVariants` + fixed positioning.
- 🎨 **Full button props** — Inherits all `ButtonProps` (color, size, variant, shape, shadow, disabled, etc.) plus `icon`/`iconClass`/`iconProps` for the default icon.
- 📡 **Events** — Emits `change` (visibility toggled) and `click` (button clicked).
- 🌐 **SSR-safe** — Guards all browser APIs (`window`, `document`, `matchMedia`); renders without errors on the server.

## Demos

Interactive demos for backtop are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Backtop.

### Backtop

#### Props
Properties for the Backtop component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ButtonVariant`; optional)
- `shape`: Shape of the component. (type `ButtonShape`; optional)
- `shadow`: Shadow style of the component. (type `ButtonShadow`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `icon`: The icon name of iconify. (type `string`; default `'lucide:arrow-up'`; optional)
- `iconClass`: The class of the icon. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `iconProps`: The props of the icon. (type `Partial<IconProps>`; optional)
- `visibilityHeight`: Scroll distance that must be reached before the Backtop button becomes visible. (type `number`; default `400`; optional)
- `target`: Scroll target that Backtop listens to and scrolls. (type `AffixTarget | null`; default `window`; optional)
- `duration`: Duration of the scroll-to-top animation in milliseconds. (type `number`; default `300`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
#### Emits
Events for the Backtop component.
- `change`: Emitted when change occurs. (type `[visible: boolean]`; parameters `visible: boolean`)
- `click`: Emitted when click occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

## Notes

### Architecture and benchmark differences

`SBacktop` splits into a headless layer that owns scroll tracking, target resolution, animation, and visibility state, and a styled layer that owns the `backtopVariants` recipe (extends `buttonVariants` with `fixed z-50` and size-based `bottom-* end-*` positioning). This follows the SoybeanUI headless/styled separation pattern.

| Aspect               | SoybeanUI                                       | Ant Design `BackTop`        | Element Plus `Backtop`      | Naive UI `BackTop`          |
| :------------------- | :---------------------------------------------- | :-------------------------- | :-------------------------- | :-------------------------- |
| Architecture         | headless + styled split                         | styled only                 | styled only                 | styled only                 |
| Smooth scrolling     | `requestAnimationFrame` + `easeInOutCubic`      | `requestAnimationFrame`     | `requestAnimationFrame`     | `requestAnimationFrame`     |
| Reduced motion       | ✅ `prefers-reduced-motion`                     | —                           | —                           | —                           |
| Target type          | `window` / `HTMLElement` / `Ref` / CSS selector | `HTMLElement` / function    | `HTMLElement` / string      | `HTMLElement` / string      |
| Visibility threshold | `visibilityHeight` (number)                     | `visibilityHeight` (number) | `visibilityHeight` (number) | `visibilityHeight` (number) |
| Animation duration   | `duration` (ms)                                 | —                           | —                           | —                           |
| Headless export      | ✅ `Backtop`                                    | —                           | —                           | —                           |
| Disabled state       | ✅ inherited from Button                        | —                           | —                           | —                           |

### Runtime cautions

- **`hidden` attribute**: When the button is not visible, the headless layer sets `hidden` on the `<button>` element, which applies `display: none`. This prevents CSS transitions on show/hide. If you need fade transitions, override `[hidden] { display: block; }` and use opacity/visibility transitions in your custom class.
- **Focus management**: When the button becomes hidden while focused (e.g., after scrolling to top), the headless layer automatically blurs it to prevent focus being trapped on a hidden element.
- **Scroll listener cleanup**: The headless layer uses `useEventListener` with `onWatcherCleanup` to remove scroll listeners when the target changes or the component unmounts. No manual cleanup is needed.
- **`target` reactivity**: Changing `target` or `visibilityHeight` at runtime triggers target re-resolution and a visibility re-check via `nextTick`.

### FAQ

**How do I target a specific scrollable container?**
Pass the element or a CSS selector: `<SBacktop target="#my-scroll-container" />` or `<SBacktop :target="scrollRef" />`. The component resolves the target and listens to its `scroll` event.

**How do I disable the smooth animation?**
Set `duration={0}`: `<SBacktop :duration="0" />`. The component also automatically skips animation when the user has `prefers-reduced-motion: reduce` enabled.

**Can I use a custom button instead of the default?**
Yes. Import the headless `Backtop` from `@soybeanjs/headless/backtop` and compose it with your own button:

```vue
<script setup lang="ts">
import { Backtop } from '@soybeanjs/headless/backtop';
</script>

<template>
  <Backtop :visibility-height="200" class="my-custom-button">
    <MyIcon />
  </Backtop>
</template>
```

**Why does the button disappear immediately after clicking?**
After scrolling to top, the scroll position drops below `visibilityHeight`, so the button hides. The headless layer blurs the button before hiding it to avoid focus being trapped on a hidden element.

**How do I change the default icon?**
Pass the `icon` prop: `<SBacktop icon="lucide:chevron-up" />`. Use `iconClass` for icon styling and `iconProps` for additional `SIcon` props.

## Badge

- Page URL: /components/badge
- Markdown URL: /components/badge.md
- Description: A small status/notification marker that overlays a trigger (button, avatar, nav item) to indicate a count, a state, or new content. SBadge is a UI-only component: a relative root plus an absolutely positioned bubble with controllable visibility, styled by the badgeVariants style recipe (2 slots: root/content; 8 colors × 6 sizes × 4 positions).

# Badge

## Overview

A small status/notification marker that overlays a trigger (button, avatar, nav item) to indicate a count, a state, or new content. `SBadge` is a **UI-only** component: a relatively positioned root plus an absolutely positioned bubble, styled by the `badgeVariants` recipe (2 slots: root/content; 8 colors × 6 sizes × 4 positions).

Use it for unread counts, notification badges, status dots, or any small label anchored to the top-right (or another corner) of a host element. Prefer `tag` for standalone inline category labels, and `alert` for contextual feedback with more content.

`SBadge` exposes a `content`-driven API with `v-model:open` control over the bubble's visibility. There is no headless `badge` family: the only logic is a controlled `open` flag, which the UI layer owns directly through `useControllableState`.

## Usage

Usage examples for badge are rendered on the site.

## Features

- 🧩 UI-only thin shell — `SBadge` owns markup and the controlled `open` state (`useControllableState`); no headless `badge` family exists
- 🔢 `content` prop / slot — a plain string or arbitrary VNode inside the bubble via the `content` slot
- 🎛️ Controlled visibility — `v-model:open` toggles whether the bubble renders (`useControllableState`, default `true`)
- 🎨 8 colors — `primary`/`destructive`/`success`/`warning`/`info`/`carbon`/`secondary`/`accent` from `ThemeColor`
- 📐 6 sizes — xs–2xl `size` from `ThemeSize`
- 📍 4 positions — `top-right`/`bottom-right`/`top-left`/`bottom-left`
- 🌐 RTL-aware — corner placement uses logical `start`/`end` properties so it mirrors under RTL
- ♿ Real content — the bubble text is rendered as real content and read by assistive technology; `axe-core` reports zero violations

## Component family

`SBadge` is a single export. It renders the `data-soybean-badge-root` container and, while `open`, the `data-soybean-badge-content` bubble; `class`/`ui` and `contentProps` reach both nodes.

## Demos

Interactive demos for badge are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (3): Badge, BadgeContent, BadgeRoot.

### Badge

#### Props
Properties for the Badge component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<BadgeUi>`; optional)
- `position`: Position. (type `BadgePosition`; optional)
- `content`: Content rendered inside the badge bubble when no content slot is provided. (type `string`; optional)
- `contentProps`: Properties forwarded to the content element. (type `BadgeContentProps`; optional)
- `open`: Whether the component is open. (type `boolean`; optional)
#### Emits
Events for the Badge component.
- `update:open`: Emitted when the open state changes. (type `[open: boolean]`; parameters `open: boolean`)
#### Slots
Slots for the Badge component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `content`: Custom content for the badge content slot. (type `(() => any) | undefined`)

### BadgeContent

- No documented props, emits, slots, or slot props were available.

### BadgeRoot

#### Props
Properties for the badge root element.
- `open`: Whether the component is open. (type `boolean`; optional)
#### Emits
Events for the badge root element.
- `update:open`: Emitted when the open state changes. (type `[open: boolean]`; parameters `open: boolean`)

## Notes

### Architecture and benchmark differences

`SBadge` owns the visibility orchestration in the UI layer — a badge is a thin shell whose only logic is a controlled `open` flag, so it deliberately has no headless family. This mirrors shadcn/ui's composition-first approach (a plain styled label there) and Radix's `Badge` primitive, unlike Ant Design, Element Plus and Naive UI which ship a single styled `Badge` with `count`/`max`/`dot`/`offset` props. SoybeanUI exposes the bubble through a `content` prop/slot and a controlled `open` state, leaving count formatting (`max`) and dot/offset convenience out of the core — see the enhancement list below.

| Capability                     | SoybeanUI | shadcn/ui | Ant Design Badge | Element Plus Badge | Mantine Badge | Naive UI Badge |
| :----------------------------- | :-------: | :-------: | :--------------: | :----------------: | :-----------: | :------------: |
| Headless/styled split          |    ✅     |    ✅     |        —         |         —          |       —       |       —        |
| Content / notification bubble  |    ✅     |     —     |        ✅        |         ✅         |       —       |       ✅       |
| Position (corner placement)    |    ✅     |     —     |        ✅        |         ✅         |       —       |       ✅       |
| Color variants (8)             |    ✅     |    ✅     |        ✅        |         ✅         |      ✅       |       ✅       |
| Size variants (6)              |    ✅     |     —     |        ✅        |         ✅         |      ✅       |       ✅       |
| RTL-aware placement            |    ✅     |     —     |        —         |         —          |       —       |       —        |
| Controlled visibility (`open`) |    ✅     |     —     |        ✅        |         ✅         |       —       |       ✅       |
| `max` count cap (99+)          |    ➕     |     —     |        ✅        |         ✅         |       —       |       ✅       |
| `dot` mode / `offset`          |    ➕     |     —     |        ✅        |         ✅         |       —       |       ✅       |

`—` = unsupported or a different interaction model; `➕` = valuable enhancement not yet provided (see below).

### Cautions

- The bubble is absolutely positioned against the root, which is `position: relative`. If the host element has `overflow: hidden`, the bubble may be clipped near the edges.
- `open` defaults to `true`. To hide the bubble use `:open="false"` or bind it with `v-model:open`.
- The bubble uses `whitespace-nowrap`; very long content will overflow instead of wrapping — keep counts short or cap them yourself until a `max` prop lands.
- The bubble text is exposed to screen readers. If it duplicates the trigger's label (e.g. a status dot on a labelled button), consider making it decorative via the `content` slot.
- Under RTL the corner placement mirrors (`top-right` stays visually top-right using logical properties); the `transform` offsets are swapped automatically.

### Roadmap

Count formatting (`max`, rendering `99+`), a bare `dot` mode, and `offset` positioning are evaluated enhancements carried in `docs/roadmap.md` — they are not part of the current public API.

## FAQ

### How do I show an unread count on a button?

Wrap the trigger and set `content`:

```vue

  <SButton variant="pure">Inbox</SButton>

```

### How do I control whether the badge is visible?

Use `v-model:open` (or `:open="false"` to hide it):

```vue

  <SButton variant="pure">Messages</SButton>

```

### How do I place the badge in a different corner?

Use `position` with one of `top-right` / `bottom-right` / `top-left` / `bottom-left`:

```vue

  <SAvatar src="/me.png" fallback-label="JD" />

```

### How do I change the color and size?

Use `color` (8 `ThemeColor` values) and `size` (xs–2xl):

```vue

```

### How do I render a custom badge bubble?

Use the `content` slot to render any VNode instead of plain text:

```vue

  <SButton variant="pure">Cart</SButton>
  <template #content><SIcon icon="lucide:bell" /></template>

```

## Breadcrumb

- Page URL: /components/breadcrumb
- Markdown URL: /components/breadcrumb.md
- Description: Breadcrumbs allow users to navigate through the hierarchy of pages. It displays the current location within the application structure.

# Breadcrumb

## Overview

Breadcrumbs allow users to navigate through the hierarchy of pages. It displays the current location within the application structure.

## Features

- **Data-driven compact composition** — `SBreadcrumb` renders items from an `items` array; the headless `BreadcrumbCompact` owns iteration, default content, and internal composition (root → list → items → separators).
- **Link vs. current page** — items with `to` / `href` render as `BreadcrumbLink` (reusing the Link primitive); the trailing item without a destination renders as `BreadcrumbPage` with `aria-current="page"` and `aria-disabled`.
- **Ellipsis collapsing** — `ellipsis: true` collapses all middle items into an ellipsis when there are 5+ items; `ellipsis: [start, end]` allows a custom collapse range (normalized so `start 0 → 1` and `end length → length - 1`).
- **Click events with item data** — the `click` event emits the full activated item object; disabled items never emit.
- **Full ARIA semantics** — `nav` carries a localized `aria-label`; separators and the ellipsis are `role="presentation"` + `aria-hidden`; the current page uses `aria-current="page"`.
- **Per-region props forwarding** — `listProps`, `itemProps`, `linkProps`, `pageProps`, `separatorProps`, `ellipsisProps` forward attributes to each region.
- **Eight customization slots** — `default`, `ellipsis`, `ellipsis-icon`, `separator`, `item-leading`, `item-link`, `item-label`, `item-trailing` with typed scoped props (`item`, `index`, `ellipsisItems`).
- **Icon support** — each item can carry an `icon` (rendered via the `item-leading` slot default) with `IconValue` typing.
- **Disabled items** — `disabled: true` on an item disables the link and suppresses click emission.
- **Size scaling** — `size` (xs…2xl) scales typography and spacing via `breadcrumbVariants`.
- **Headless composition** — `BreadcrumbRoot` / `BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbSeparator` / `BreadcrumbEllipsis` are exported from `@soybeanjs/headless/breadcrumb` for fully custom styled builds.

## Usage

Usage examples for breadcrumb are rendered on the site.

> `SBreadcrumb` delegates its list aggregation to headless `BreadcrumbCompact`. For unstyled, data-driven composition, import `BreadcrumbCompact` from `@soybeanjs/headless/breadcrumb`.

## Demos

Interactive demos for breadcrumb are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (11): Breadcrumb, BreadcrumbCompact, BreadcrumbCompactEllipsis, BreadcrumbCompactItem, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbRoot, BreadcrumbSeparator.

### Breadcrumb

#### Props
Properties for the Breadcrumb component.
- `class`: root class (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<BreadcrumbUi>`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `ellipsis`: The range of items to show ellipsis. When the item count is greater than 4, we will show ellipsis. (type `true | [number, number] | null`; optional)
- `listProps`: Properties forwarded to the list element. (type `BreadcrumbListProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `BreadcrumbItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `pageProps`: Properties forwarded to the page element. (type `BreadcrumbPageProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `BreadcrumbSeparatorProps`; optional)
- `ellipsisProps`: Properties forwarded to the ellipsis element. (type `BreadcrumbEllipsisProps`; optional)
#### Emits
Events for the Breadcrumb component.
- `click`: Emitted when click occurs. (type `[item: T]`; parameters `item: T`)
#### Slots
Slots for the Breadcrumb component.
- `default`: Custom content for the default slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `ellipsis`: Custom content for the ellipsis slot. (type `((props: BreadcrumbCompactEllipsisSlotProps<T>) => any) | undefined`)
- `ellipsis-icon`: Custom content for the ellipsis icon slot. (type `(() => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `(() => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `item-link`: Custom content for the item link slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `item-label`: Custom content for the item label slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)

### BreadcrumbCompact

#### Props
Properties for the BreadcrumbCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `ellipsis`: The range of items to show ellipsis. When the item count is greater than 4, we will show ellipsis. (type `true | [number, number] | null`; optional)
- `listProps`: Properties forwarded to the list element. (type `BreadcrumbListProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `BreadcrumbItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `pageProps`: Properties forwarded to the page element. (type `BreadcrumbPageProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `BreadcrumbSeparatorProps`; optional)
- `ellipsisProps`: Properties forwarded to the ellipsis element. (type `BreadcrumbEllipsisProps`; optional)
#### Emits
Events for the BreadcrumbCompact component.
- `click`: Emitted when click occurs. (type `[item: T]`; parameters `item: T`)
#### Slots
Slots for the BreadcrumbCompact component.
- `default`: Custom content for the default slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `ellipsis`: Custom content for the ellipsis slot. (type `((props: BreadcrumbCompactEllipsisSlotProps<T>) => any) | undefined`)
- `ellipsis-icon`: Custom content for the ellipsis icon slot. (type `(() => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `(() => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `item-link`: Custom content for the item link slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `item-label`: Custom content for the item label slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: BreadcrumbCompactItemSlotProps<T>) => any) | undefined`)

### BreadcrumbCompactEllipsis

#### Slot Props
Slot properties for the BreadcrumbCompactEllipsis component.
- `ellipsisItems`: Ellipsis items exposed in the slot scope. (type `T[]`; required)

### BreadcrumbCompactItem

#### Slot Props
Slot properties for the BreadcrumbCompactItem component.
- `item`: Current item data. (type `T`; required)
- `index`: Index of the current item. (type `number`; required)

### BreadcrumbEllipsis

- No documented props, emits, slots, or slot props were available.

### BreadcrumbItem

- No documented props, emits, slots, or slot props were available.

### BreadcrumbLink

#### Props
Properties for the BreadcrumbLink component.
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `replace`: Calls `router.replace` instead of `router.push`. (type `boolean`; optional)
- `href`: The URL the link should navigate to when clicked on. (type `string`; optional)
- `disabled`: When `true`, the link is disabled. (type `boolean`; optional)
- `activeClass`: Class to apply when the link is active (type `string`; optional)
- `exactActiveClass`: Class to apply when the link is exact active (type `string`; optional)
- `inactiveClass`: The class to apply to the link when it is inactive. (type `string`; optional)
- `prefetchedClass`: A class to apply to links that have been prefetched. (type `string`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `ariaCurrentValue`: Value passed to the attribute `aria-current` when the link is exact active. (type `'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location'`; default ``'page'``; optional)
- `viewTransition`: Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported. (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)
- `rel`: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links. (type `(string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null`; default `'noopener noreferrer'`; optional)
- `noRel`: If set to true, no rel attribute will be added to the link (type `boolean`; optional)
- `prefetch`: When enabled will prefetch middleware, layouts and payloads of links in the viewport. (type `boolean`; optional)
- `prefetchOn`: Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility. (type `'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }>`; optional)
- `noPrefetch`: Escape hatch to disable `prefetch` attribute. (type `boolean`; optional)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href` for this specific link. Overrides the global `trailingSlash` option if provided. (type `'append' | 'remove'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### BreadcrumbList

- No documented props, emits, slots, or slot props were available.

### BreadcrumbPage

- No documented props, emits, slots, or slot props were available.

### BreadcrumbRoot

- No documented props, emits, slots, or slot props were available.

### BreadcrumbSeparator

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark comparison

| Concern                       | SoybeanUI                                             | shadcn-vue `Breadcrumb`                       | Ant Design `Breadcrumb`            | Element Plus `Breadcrumb`     |
| :---------------------------- | :---------------------------------------------------- | :-------------------------------------------- | :--------------------------------- | :---------------------------- |
| Headless / styled separation  | ✅ `@soybeanjs/headless/breadcrumb` + `scv()`         | ❌ single package                             | ❌ single package                  | ❌ single package             |
| Data-driven compact API       | ✅ `items` + `ellipsis` + `click`                     | ❌ slot/component composition only            | ✅ `routes` / `items`              | ✅ `breadcrumb-item` loop     |
| Ellipsis collapsing           | ✅ `true` (5+ items) or custom `[start, end]`         | ❌ manual ellipsis item                       | ✅ `ellipsis` (4+ count)           | ❌ manual                     |
| Link vs. current page         | ✅ `to`/`href` → Link; trailing → `aria-current` page | ✅ separate `BreadcrumbLink`/`BreadcrumbPage` | ✅ `BreadcrumbItem` last = current | ✅ last item auto current     |
| Click event with item data    | ✅ `click(item)`; disabled suppressed                 | ❌ native link only                           | ✅ `onClick(route)`                | ✅ `select` event             |
| Disabled items                | ✅ `disabled` on item data                            | —                                             | ✅                                 | —                             |
| Localized `aria-label`        | ✅ locale registry                                    | hard-coded                                    | `itemRender` only                  | —                             |
| Region-level props forwarding | ✅ 6 props groups                                     | `asChild` per part                            | `itemRender`                       | `separator` slot              |
| Customization slots           | ✅ 8 typed slots                                      | ✅ 5 parts + separator slot                   | `itemRender`                       | ✅ `separator` / `title` slot |
| Size scaling                  | ✅ xs…2xl                                             | ✅ fixed                                      | ✅ `size`                          | —                             |

### Runtime considerations

1. **Ellipsis index math** — `getEllipsisRange` returns `null` below 5 items; `[1, len-2]` for `true`; user ranges are normalized (`start 0 → 1`, `end length → length - 1`) to always keep the first and last item visible.
2. **Ellipsis placement** — the collapsed ellipsis is rendered at the new-array index matching `start`, i.e. directly before the first post-collapse item; a separator follows the ellipsis.
3. **Disabled click suppression** — `handleItemClick` ignores items with `disabled: true`, so the `click` event never carries a disabled item (link clicks are also blocked by the Link primitive).
4. **Link routing** — `BreadcrumbLink` extends the Link primitive, so `to` (router-link) and `href` / `external` (anchor) both work; `target` is honored.
5. **Current page semantics** — the last item without `to`/`href` renders as `BreadcrumbPage` (`role="link"` + `aria-disabled="true"` + `aria-current="page"`), so AT users know it is not a navigable link.
6. **Locale fallback** — the `nav` `aria-label` comes from `useLocaleMessages`; missing locale keys fall back to the default English bundle.

## FAQ

### When does the ellipsis appear?

With `ellipsis: true`, the ellipsis renders only when there are 5 or more items; the first and last items always stay visible and the middle ones are collapsed. Use `ellipsis: [start, end]` to pick exactly which range collapses (both endpoints are normalized to keep the edges visible).

### How do I make an item a link vs. the current page?

An item with `to` (router) or `href`/`external` (anchor) renders as a link. The trailing item without a destination renders as the current page with `aria-current="page"`. To force a non-last item to be a plain label, omit `to`/`href` on it.

### Why doesn't clicking a disabled item emit anything?

Disabled items are intentionally inert: the link is disabled by the Link primitive and the compact component suppresses the `click` event for `disabled: true` items, matching the expected breadcrumb behavior.

### Can I customize the separator?

Yes — use the `separator` slot. Each separator (including the one after the ellipsis) renders your content. For per-region styling, pass `separatorProps` or the `ui` recipe classes.

### What scoped props do the item slots receive?

`item-leading`, `item-link`, `item-label`, `item-trailing`, and the default slot receive `{ item, index }`; the `ellipsis` slot receives `{ ellipsisItems }`. The UI wrapper forwards these unchanged to your custom slot content.

### Is the breadcrumb accessible?

Yes — the root is a `nav` with a localized `aria-label`, the list is an `ol`, separators and the ellipsis are hidden from assistive technology, and the current page is announced via `aria-current="page"`.

### Can I build a fully custom breadcrumb?

Yes — compose `BreadcrumbRoot` / `BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbSeparator` / `BreadcrumbEllipsis` from `@soybeanjs/headless/breadcrumb` and inject styles via `provideBreadcrumbUi` (or `SBreadcrumb`'s `ui` prop).

## Button

- Page URL: /components/button
- Markdown URL: /components/button.md
- Description: A button component that can be used to trigger an action.

# Button

## Overview

A button component that can be used to trigger an action.

## Usage

Usage examples for button are rendered on the site.

## Features

- 🎨 8 variants: solid, outline, dashed, soft, ghost, link, plain, pure
- 🌈 8 colors: primary, destructive, success, warning, info, carbon, secondary, accent
- 📏 6 sizes: xs, sm, md, lg, xl, 2xl
- 🔲 4 shapes: auto, rounded, square, circle
- ⚡ Loading state support
- 🌐 Link function support (SButtonLink)
- ♿ Full accessibility support
- 🎯 TypeScript type safety

## Button component family

- **SButton** - Basic button component
- **SButtonLink** - Link button, supports route navigation
- **SButtonIcon** - Icon button, compact design
- **SButtonLoading** - Loading state button
- **SButtonGroup** - Button group component

## Demos

Interactive demos for button are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Button, ButtonGroup, ButtonIcon, ButtonLink, ButtonLoading.

### Button

#### Props
Properties for the Button component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ButtonVariant`; optional)
- `shape`: Shape of the component. (type `ButtonShape`; optional)
- `shadow`: Shadow style of the component. (type `ButtonShadow`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Button component.
- `click`: Emitted when click occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### ButtonGroup

#### Props
Properties for the ButtonGroup component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ButtonVariant`; optional)
- `shape`: Shape of the component. (type `ButtonShape`; optional)
- `shadow`: Shadow style of the component. (type `ButtonShadow`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `disabled`: Whether all descendant buttons are disabled. (type `boolean`; optional)
- `orientation`: The orientation of the button group. (type `DataOrientation`; default `'horizontal'`; optional)
- `dir`: The reading direction of the button group. (type `Direction`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ButtonIcon

#### Props
Properties for the ButtonIcon component.
- `icon`: The icon value of iconify. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; required)
- `iconClass`: The class of the icon. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `iconProps`: The props of the icon. (type `Partial<IconProps>`; optional)
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ButtonVariant`; optional)
- `shape`: Shape of the component. (type `ButtonShape`; optional)
- `shadow`: Shadow style of the component. (type `ButtonShadow`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ButtonLink

#### Props
Properties for the ButtonLink component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `'primary' | 'secondary' | 'accent' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon'`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ButtonVariant`; optional)
- `shape`: Shape of the component. (type `ButtonShape`; optional)
- `shadow`: Shadow style of the component. (type `ButtonShadow`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. When `true`, the link is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `replace`: Calls `router.replace` instead of `router.push`. (type `boolean`; optional)
- `href`: The URL the link should navigate to when clicked on. (type `string`; optional)
- `activeClass`: Class to apply when the link is active (type `string`; optional)
- `exactActiveClass`: Class to apply when the link is exact active (type `string`; optional)
- `inactiveClass`: The class to apply to the link when it is inactive. (type `string`; optional)
- `prefetchedClass`: A class to apply to links that have been prefetched. (type `string`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `ariaCurrentValue`: Value passed to the attribute `aria-current` when the link is exact active. (type `'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location'`; default ``'page'``; optional)
- `viewTransition`: Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported. (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)
- `rel`: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links. (type `(string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null`; default `'noopener noreferrer'`; optional)
- `noRel`: If set to true, no rel attribute will be added to the link (type `boolean`; optional)
- `prefetch`: When enabled will prefetch middleware, layouts and payloads of links in the viewport. (type `boolean`; optional)
- `prefetchOn`: Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility. (type `'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }>`; optional)
- `noPrefetch`: Escape hatch to disable `prefetch` attribute. (type `boolean`; optional)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href` for this specific link. Overrides the global `trailingSlash` option if provided. (type `'append' | 'remove'`; optional)

### ButtonLoading

#### Props
Properties for the ButtonLoading component.
- `loading`: Whether the button is loading. (type `boolean`; default `false`; optional)
- `loadingText`: The text to display when the button is loading. It will be displayed when the loading position is center. (type `string`; optional)
- `loadingDuration`: The duration of the loading state in milliseconds. (type `number`; default `150 ms`; optional)
- `autoLoading`: Whether to automatically handle loading state during click event. When true, the button will show loading state during click event execution. When false, you need to manually control the loading state. (type `boolean`; default `false`; optional)
- `loadingIcon`: The icon name of iconify to display when the button is loading. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; default `'svg-spinners:270-ring'`; optional)
- `loadingIconProps`: The props of the loading icon. (type `Partial<IconProps>`; optional)
- `loadingPosition`: The position of the loading icon. (type `Align`; default `'start'`; optional)
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ButtonVariant`; optional)
- `shape`: Shape of the component. (type `ButtonShape`; optional)
- `shadow`: Shadow style of the component. (type `ButtonShadow`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the button into a headless layer (`@soybeanjs/headless/button`) that owns state, ARIA, and keyboard behavior, and a styled layer (`@soybeanjs/ui`) that owns variants and UnoCSS classes. This mirrors `shadcn/ui`'s headless/styled separation and differs from single-package libraries such as Ant Design, Element Plus, MUI, Mantine, and Naive UI.

| Aspect        | SoybeanUI                                                   | Ant Design / Element Plus / MUI / Mantine / Naive UI |
| :------------ | :---------------------------------------------------------- | :--------------------------------------------------- |
| Architecture  | headless + styled split                                     | single package                                       |
| Styling       | UnoCSS utility classes via `cv()` recipe                    | CSS-in-JS / SCSS / CSS vars                          |
| Customization | `class` prop, `as` / `asChild` polymorphism, slot overrides | `className`, `style`, component overrides            |
| Loading       | dedicated `SButtonLoading` component                        | `loading` prop on the base button                    |
| Icon button   | dedicated `SButtonIcon` component                           | `icon` prop on the base button                       |

### FAQ

**Why does the disabled button keep `aria-disabled` in addition to the native `disabled`?**
The native `disabled` attribute removes the button from the tab order and blocks platform-level clicks. `aria-disabled="true"` is also set so assistive technology can announce the disabled state when the button is rendered as a non-`<button>` element through the `as` prop (e.g. `as="a"` or `as="div"`), where the native `disabled` attribute does not apply.

**How do I make a full-width button?**
Pass `class="w-full"` (or `fitContent` for the opposite effect). SoybeanUI does not add a `block` prop because UnoCSS utilities cover this without expanding the API surface.

**How do I show a loading indicator?**
Use `SButtonLoading`. It supports `autoLoading` (toggles loading during the click handler), a controlled `loading` prop, `loadingPosition` (`start` / `center` / `end`), `loadingText`, and a custom `loadingIcon`. The base `SButton` intentionally stays loading-free to keep its API minimal. While loading, the button sets `aria-busy="true"` and the loading icon is `aria-hidden` so the state is announced without redundant decoration.

**How does `SButtonGroup` propagate props to children?**
`SButtonGroup` provides a context that forwards `color`, `size`, `variant`, `shape`, `shadow`, `disabled`, and `fitContent` to descendant `SButton` instances. A child's own prop takes precedence over the group's value.

**Can I render the button as a link or another element?**
Yes. Use the `as` prop to change the root tag (`as="a"`, `as="div"`, …), or `asChild` to merge props onto a custom child. For routing-aware link buttons, prefer `SButtonLink`, which composes `SButton` with the `Link` component.

## Calendar

- Page URL: /components/calendar
- Markdown URL: /components/calendar.md
- Description: A monthly date grid that supports single or multiple selection, disabled and unavailable dates, min/max bounds, custom cell rendering, and month/year Select controls in the compact header. Use it for booking, scheduling, or any date-picking surface that needs keyboard-navigable grids instead of a plain text input. Pair it with SDatePicker when you need a popup trigger, or SRangeCalendar-style composites for range selection.

# Calendar

## Overview

A monthly date grid that supports single or multiple selection, disabled and unavailable dates, min/max bounds, custom cell rendering, and month/year Select controls in the compact header. Use it for booking, scheduling, or any date-picking surface that needs keyboard-navigable grids instead of a plain text input. Pair it with `SDatePicker` when you need a popup trigger, or `SRangeCalendar`-style composites for range selection.

## Usage

Usage examples for calendar are rendered on the site.

## Features

- 📅 Month grid — one or more month grids (`numberOfMonths`) with locale-aware weekday headers, today, and outside-view markers
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` for single dates or date arrays (`multiple`), backed by `useControllableState`
- ✅ Multiple selection — click or keyboard-toggle dates; `preventDeselect` keeps the selection sticky
- ⌨️ Full keyboard support — `ArrowLeft`/`ArrowRight`/`ArrowUp`/`ArrowDown` navigation with RTL reversal, cross-month paging, and disabled-date skipping; `Enter`/`Space` selects
- ⛓ Bounds & matching — `minValue`/`maxValue` clamp the page and disable out-of-range dates; `isDateDisabled`/`isDateUnavailable` mark arbitrary dates
- 🧩 Composable slots — `day`, `head-cell`, `heading`, `prev`, and `next` slots with rich slot props; `*Props` passthrough for every sub-part
- 🔤 Localized UI — `locale`, `weekStartsOn`, and `weekdayFormat`; month/year Select controls carry localized `aria-label`s
- 🗓 Month/year controls — compact header renders Select controls for fast month/year jumps, disabled per `minValue`/`maxValue`
- ↕️ Fixed weeks — `fixedWeeks` renders a consistent 6-row grid; `initialFocus` moves focus into the grid on mount
- 🚫 Disabled / readonly — `disabled` blocks all interaction; `readonly` keeps browsing but blocks selection

## Component family

- `SCalendar` — the styled wrapper that forwards props to the headless compact and injects `calendarVariants` classes (12 slots, shared button icon recipes for prev/next)
- `CalendarCompact` (headless) — data-driven composition of `CalendarRoot` + header (prev/heading/next) + one grid per month (grid head/body rows of `CalendarCellTrigger`); import from `@soybeanjs/headless/calendar` for unstyled usage
- `CalendarRoot` (headless) — state owner: `useControllableState` for value/placeholder, `useCalendar` for grid/month pages and validation, `useCalendarState` for selected/invalid state
- `CalendarCellTrigger` / `CalendarCell` / `CalendarGrid*` (headless) — the editable day button (keyboard handling, focus management, data attributes) and its semantic grid cell wrappers

## Demos

Interactive demos for calendar are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (14): Calendar, CalendarCell, CalendarCellTrigger, CalendarCompact, CalendarGrid, CalendarGridBody, CalendarGridHead, CalendarGridRow, CalendarHeadCell, CalendarHeader, CalendarHeading, CalendarNext, CalendarPrev, CalendarRoot.

### Calendar

#### Props
Properties for the Calendar component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CalendarUi>`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CalendarHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarPrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarCellTriggerProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `locale`: Locale. (type `string`; optional)
- `modelValue`: Current model value. (type `CalendarModelValue<M>`; optional)
- `defaultValue`: Default value. (type `CalendarModelValue<M>`; optional)
- `multiple`: Whether multiple values are supported. (type `M`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Calendar component.
- `update:modelValue`: Emitted when the model value changes. (type `[date: CalendarModelValue<M>]`; parameters `date: CalendarModelValue<M>`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
#### Slots
Slots for the Calendar component.
- `default`: Custom content for the default slot. (type `((props: { modelValue: CalendarModelValue<M>; }) => any) | undefined`)
- `prev`: Custom content for the prev slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `heading`: Custom content for the heading slot. (type `((props: CalendarHeadingSlotProps) => any) | undefined`)
- `next`: Custom content for the next slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `head-cell`: Custom content for the head cell slot. (type `((props: { date: Date; index: number; label: string; }) => any) | undefined`)
- `day`: Custom content for the day slot. (type `((props: CalendarDaySlotProps) => any) | undefined`)

### CalendarCell

#### Props
Properties for the CalendarCell component.
- `date`: Date. (type `Date`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarCellTrigger

#### Props
Properties for the CalendarCellTrigger component.
- `day`: Day. (type `Date`; required)
- `month`: Month. (type `Date`; required)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the CalendarCellTrigger component.
- `default`: Custom content for the default slot. (type `((props: CalendarCellTriggerSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the CalendarCellTrigger component.
- `dayValue`: Day value string exposed in the slot scope. (type `string`; required)
- `disabled`: Whether the date is disabled. (type `boolean`; required)
- `selected`: Whether the date is selected. (type `boolean`; required)
- `unavailable`: Whether the date is unavailable. (type `boolean`; required)
- `today`: Whether the date is today. (type `boolean`; required)
- `outsideView`: Whether the date is outside the current view. (type `boolean`; required)
- `outsideVisibleView`: Whether the date is outside the visible view. (type `boolean`; required)

### CalendarCompact

#### Props
Properties for the CalendarCompact component.
- `headerProps`: Properties forwarded to the header element. (type `CalendarHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarPrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarCellTriggerProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `locale`: Locale. (type `string`; optional)
- `modelValue`: Current model value. (type `CalendarModelValue<M>`; optional)
- `defaultValue`: Default value. (type `CalendarModelValue<M>`; optional)
- `multiple`: Whether multiple values are supported. (type `M`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CalendarCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[date: CalendarModelValue<M>]`; parameters `date: CalendarModelValue<M>`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
#### Slots
Slots for the CalendarCompact component.
- `default`: Custom content for the default slot. (type `((props: { modelValue: CalendarModelValue<M>; }) => any) | undefined`)
- `prev`: Custom content for the prev slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `heading`: Custom content for the heading slot. (type `((props: CalendarHeadingSlotProps) => any) | undefined`)
- `next`: Custom content for the next slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `head-cell`: Custom content for the head cell slot. (type `((props: { date: Date; index: number; label: string; }) => any) | undefined`)
- `day`: Custom content for the day slot. (type `((props: CalendarDaySlotProps) => any) | undefined`)

### CalendarGrid

#### Props
Properties for the CalendarGrid component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarGridBody

#### Props
Properties for the CalendarGridBody component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarGridHead

#### Props
Properties for the CalendarGridHead component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarGridRow

#### Props
Properties for the CalendarGridRow component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarHeadCell

#### Props
Properties for the CalendarHeadCell component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarHeader

#### Props
Properties for the CalendarHeader component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarHeading

#### Props
Properties for the CalendarHeading component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slot Props
Slot properties for the CalendarHeading component.
- `selectedMonth`: No description. (type `number`; required)
- `selectedYear`: No description. (type `number`; required)
- `headingValue`: Heading value exposed in the slot scope. (type `string`; required)
- `yearOptions`: Year options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onYearChange`: Callback invoked when the year changes. (type `(value?: number | undefined) => void`; required)
- `monthOptions`: Month options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onMonthChange`: Callback invoked when the month changes. (type `(value?: number | undefined) => void`; required)

### CalendarNext

#### Props
Properties for the CalendarNext component.
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarPrev

#### Props
Properties for the CalendarPrev component.
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRoot

#### Props
Properties for the CalendarRoot component.
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `locale`: Locale. (type `string`; optional)
- `modelValue`: Current model value. (type `CalendarModelValue<M>`; optional)
- `defaultValue`: Default value. (type `CalendarModelValue<M>`; optional)
- `multiple`: Whether multiple values are supported. (type `M`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CalendarRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[date: CalendarModelValue<M>]`; parameters `date: CalendarModelValue<M>`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
#### Slots
Slots for the Calendar component.
- `default`: Custom content for the default slot. (type `((props: CalendarRootSlotProps<M>) => any) | undefined`)
#### Slot Props
Slot properties for the CalendarRoot component.
- `date`: Date exposed in the slot scope. (type `Date | import("../../date").DateTimeValue`; required)
- `headingValue`: Heading value exposed in the slot scope. (type `string`; required)
- `placeholder`: Placeholder exposed in the slot scope. (type `Date | import("../../date").DateTimeValue`; required)
- `grid`: Grid exposed in the slot scope. (type `DateGrid<Date>[]`; required)
- `weekDays`: Week days exposed in the slot scope. (type `string[]`; required)
- `weekStartsOn`: Week starts on exposed in the slot scope. (type `number`; required)
- `locale`: Locale exposed in the slot scope. (type `string`; required)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; required)
- `modelValue`: Current model value. (type `M extends true ? DateValue[] | undefined : DateValue | undefined`; required)
- `formatter`: Formatter exposed in the slot scope. (type `Formatter`; required)
- `minValue`: Min value exposed in the slot scope. (type `DateValue | undefined`; required)
- `maxValue`: Max value exposed in the slot scope. (type `DateValue | undefined`; required)
- `disabled`: Whether the component is disabled. (type `boolean`; required)
- `onPlaceholderChange`: Callback invoked when the placeholder changes. (type `(date: DateValue) => void`; required)
- `yearOptions`: Year options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onYearChange`: Callback invoked when the year changes. (type `(value?: number | undefined) => void`; required)
- `monthOptions`: Month options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onMonthChange`: Callback invoked when the month changes. (type `(value?: number | undefined) => void`; required)

## Notes

### Architecture and benchmark differences

`CalendarRoot` owns the value via `useControllableState` (single date or array when `multiple`), keeps the placeholder for grid paging, and delegates grid creation to `useCalendar` (which rebuilds the grid on locale/week-start/placeholder changes and clamps pages with `minValue`/`maxValue`). `useCalendarState` derives selected/invalid state. `CalendarCellTrigger` is the only interactive piece: it reads the shared context, computes `data-focused`/`data-selected`/`data-today`/`data-unavailable`/`data-outside-view`, handles Arrow/Enter/Space keys with `dir`-aware direction (RTL flips ArrowLeft/ArrowRight), and pages to adjacent months when navigation crosses the grid boundary. The compact owns iteration over months/weeks/days and the header wiring (prev/heading/next with month/year Select controls). Most benchmark libraries ship a monolithic calendar panel; the headless/styled split, per-part `*Props` passthrough, and slot-driven cell rendering are the differentiators.

| Capability                     | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :----------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split          |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Single / multiple selection    |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Keyboard grid navigation       |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   ✅   |
| RTL direction reversal         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| `numberOfMonths` grid          |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| `minValue`/`maxValue` bounds   |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isDateDisabled` / unavailable |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `fixedWeeks` / `weekStartsOn`  |    ✅     |     —      |      ✅      |   ✅    |    —     |   —    |
| Month/year Select controls     |    ✅     |     ✅     |      ✅      |    —    |    —     |   —    |
| Custom `prevPage`/`nextPage`   |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Per-part `*Props` passthrough  |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Localized `aria-label`s        |    ✅     |     ✅     |      ✅      |   ✅    |    —     |   —    |

### Cautions

- The value is a native `Date` at local midnight (the `DateValue` model: `Date` or `{ date, time? }`). Use `date-fns` or `Intl` when formatting or converting.
- `multiple` changes the model shape to `DateValue[]`; the `M` generic infers it from the prop.
- `defaultValue`/`defaultPlaceholder` are read on mount only — use `v-model` for external control.
- `isDateDisabled` and `isDateUnavailable` differ: disabled dates are unselectable by policy, unavailable dates are additionally marked visually (`line-through` in the default style).
- Dates outside the current month are rendered by default; pass `disableDaysOutsideCurrentView` to disable them.
- The prev/next `aria-label`s default to locale messages; override per button through `prevProps`/`nextProps`.
- Navigation buttons auto-disable at `minValue`/`maxValue`; custom `prevPage`/`nextPage` functions take part in that computation.

## FAQ

### How do I select multiple dates?

Pass `multiple` (boolean shorthand works in templates) and bind `v-model` to an array of `DateValue`s. Clicking toggles dates; `preventDeselect` stops removal.

### How do I prevent dates before today?

Pass `minValue={new Date(2026, 0, 1)}` (or any `DateValue`). Out-of-range dates are disabled and the prev button auto-disables at the bound.

### How do I show several months at once?

Set `numberOfMonths={2}` — the calendar renders two month grids side by side and pages both when crossing the boundary.

### Why is `PageUp`/`PageDown` not handled?

Grid navigation currently covers Arrow keys, `Enter`/`Space`, and cross-month paging. `PageUp`/`PageDown`/`Home`/`End` (present in Ant Design/Element Plus panels) are a scheduled enhancement.

### How do I build a date range with this component?

Use `SRangeCalendar` for a dedicated range grid, or pair two `SCalendar`s with `minValue`/`maxValue` bound to the other side's selection.

## CalendarRange

- Page URL: /components/calendar-range
- Markdown URL: /components/calendar-range.md
- Description: CalendarRange displays one or more month grids and lets users pick a start and end date directly from the calendar surface. Selecting the first date starts the range, a live hover preview highlights the candidate range, and the second click commits it — with reversed selections sorted automatically. Use it for booking, scheduling, or any range-picking surface that needs a keyboard-navigable grid instead of two text inputs. Pair it with SDateRangePicker when you need a popup trigger, or use it standalone inside forms and custom layouts.

# CalendarRange

## Overview

CalendarRange displays one or more month grids and lets users pick a start and end date directly from the calendar surface. Selecting the first date starts the range, a live hover preview highlights the candidate range, and the second click commits it — with reversed selections sorted automatically. Use it for booking, scheduling, or any range-picking surface that needs a keyboard-navigable grid instead of two text inputs. Pair it with `SDateRangePicker` when you need a popup trigger, or use it standalone inside forms and custom layouts.

## Usage

Usage examples for calendar-range are rendered on the site.

## Features

- 📅 Month grids — one or more grids (`numberOfMonths`) with locale-aware weekday headers, today, and outside-view markers
- 🎯 Range picking — click start then end (in either order, sorted automatically); hover previews the candidate range before commit
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` bound to a `DateRange` (`{ start, end }`), backed by `useControllableState`
- ⌨️ Full keyboard support — `ArrowLeft`/`ArrowRight`/`ArrowUp`/`ArrowDown` navigation with RTL reversal, cross-month paging, and disabled-date skipping; `Enter`/`Space` selects the start/end
- ⛓ Range constraints — `allowNonContiguousRanges` toggles gaps, `maximumDays` caps the span, `isDateDisabled`/`isDateUnavailable`/`isDateHighlightable` control every day, `minValue`/`maxValue` clamp the page
- 📌 Fixed anchors — `fixedDate` (`'start'`/`'end'`) keeps one end pinned while re-picking the other; `preventDeselect` keeps a lone start sticky
- 🧩 Composable slots — `day`, `head-cell`, `heading`, `prev`, and `next` slots with rich slot props; `*Props` passthrough for every sub-part
- 🔤 Localized UI — `locale`, `weekStartsOn`, and `weekdayFormat`; month/year Select controls carry localized `aria-label`s
- 🚫 Disabled / readonly — `disabled` blocks all interaction; `readonly` keeps browsing but blocks selection
- ↕️ Fixed weeks — `fixedWeeks` renders a consistent 6-row grid; `initialFocus` moves focus into the grid on mount
- 🖱 Live hover preview — `data-highlighted`/`data-highlighted-start`/`data-highlighted-end` attributes drive range preview styling while picking the end

## Component family

- `SCalendarRange` — the styled wrapper that forwards props to the headless compact, injects `calendarRangeVariants` classes (12 slots, shared button icon recipes), and renders the default month/year Select controls in the heading
- `CalendarRangeCompact` (headless) — data-driven composition of `CalendarRangeRoot` + header (prev/heading/next) + one grid per month (grid head/body rows of `CalendarRangeCellTrigger`); import from `@soybeanjs/headless/calendar-range` for unstyled usage
- `CalendarRangeRoot` (headless) — state owner: `useControllableState` for `DateRange`/placeholder, `useCalendar` for grid/month pages, `useCalendarRangeState` for selected/highlighted/invalid state and candidate-range validation
- `CalendarRangeCellTrigger` / `CalendarRangeCell` / `CalendarRangeGrid*` (headless) — the editable day button (keyboard handling, focus management, range data attributes) and its semantic grid cell wrappers

## Demos

Interactive demos for calendar-range are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (14): CalendarRange, CalendarRangeCell, CalendarRangeCellTrigger, CalendarRangeCompact, CalendarRangeGrid, CalendarRangeGridBody, CalendarRangeGridHead, CalendarRangeGridRow, CalendarRangeHeadCell, CalendarRangeHeader, CalendarRangeHeading, CalendarRangeNext, CalendarRangePrev, CalendarRangeRoot.

### CalendarRange

#### Props
Properties for the CalendarRange component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CalendarRangeUi>`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CalendarRangeHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarRangeHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarRangePrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarRangeNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarRangeGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarRangeGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarRangeGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarRangeGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarRangeHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarRangeCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarRangeCellTriggerProps`; optional)
- `defaultValue`: Default value. (type `DateRange`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `allowNonContiguousRanges`: Whether to allow non contiguous ranges. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `maximumDays`: Maximum days. (type `number`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `locale`: Locale. (type `string`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `isDateHighlightable`: Whether a date highlightable. (type `DateMatcher`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `fixedDate`: Fixed date. (type `'start' | 'end'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CalendarRange component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the CalendarRange component.
- `default`: Custom content for the default slot. (type `((props: { modelValue: DateRange; }) => any) | undefined`)
- `prev`: Custom content for the prev slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `heading`: Custom content for the heading slot. (type `((props: CalendarRangeHeadingSlotProps) => any) | undefined`)
- `next`: Custom content for the next slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `head-cell`: Custom content for the head cell slot. (type `((props: { date: Date; index: number; label: string; }) => any) | undefined`)
- `day`: Custom content for the day slot. (type `((props: CalendarRangeDaySlotProps) => any) | undefined`)

### CalendarRangeCell

#### Props
Properties for the CalendarRangeCell component.
- `date`: Date. (type `Date | import("../../date").DateTimeValue`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeCellTrigger

#### Props
Properties for the CalendarRangeCellTrigger component.
- `day`: Day. (type `Date`; required)
- `month`: Month. (type `Date`; required)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the CalendarRangeCellTrigger component.
- `default`: No description. (type `((props: CalendarRangeCellTriggerSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the CalendarRangeCellTrigger component.
- `dayValue`: Day value string exposed in the slot scope. (type `string`; required)
- `disabled`: Whether the date is disabled. (type `boolean`; required)
- `selected`: Whether the date is selected. (type `boolean`; required)
- `unavailable`: Whether the date is unavailable. (type `boolean`; required)
- `today`: Whether the date is today. (type `boolean`; required)
- `outsideView`: Whether the date is outside the current view. (type `boolean`; required)
- `outsideVisibleView`: Whether the date is outside the visible view. (type `boolean`; required)
- `highlighted`: Whether the date is focused. (type `boolean`; required)
- `highlightedStart`: Whether the date is a highlighted start. (type `boolean`; required)
- `highlightedEnd`: Whether the date is a highlighted end. (type `boolean`; required)
- `selectionStart`: Whether the date is a selection start. (type `boolean`; required)
- `selectionEnd`: Whether the date is a selection end. (type `boolean`; required)

### CalendarRangeCompact

#### Props
Properties for the CalendarRangeCompact component.
- `headerProps`: Properties forwarded to the header element. (type `CalendarRangeHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarRangeHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarRangePrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarRangeNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarRangeGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarRangeGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarRangeGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarRangeGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarRangeHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarRangeCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarRangeCellTriggerProps`; optional)
- `defaultValue`: Default value. (type `DateRange`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `allowNonContiguousRanges`: Whether to allow non contiguous ranges. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `maximumDays`: Maximum days. (type `number`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `locale`: Locale. (type `string`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `isDateHighlightable`: Whether a date highlightable. (type `DateMatcher`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `fixedDate`: Fixed date. (type `'start' | 'end'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CalendarRangeCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the CalendarRangeCompact component.
- `default`: Custom content for the default slot. (type `((props: { modelValue: DateRange; }) => any) | undefined`)
- `prev`: Custom content for the prev slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `heading`: Custom content for the heading slot. (type `((props: CalendarRangeHeadingSlotProps) => any) | undefined`)
- `next`: Custom content for the next slot. (type `((props: { disabled: boolean; }) => any) | undefined`)
- `head-cell`: Custom content for the head cell slot. (type `((props: { date: Date; index: number; label: string; }) => any) | undefined`)
- `day`: Custom content for the day slot. (type `((props: CalendarRangeDaySlotProps) => any) | undefined`)

### CalendarRangeGrid

#### Props
Properties for the CalendarRangeGrid component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeGridBody

#### Props
Properties for the CalendarRangeGridBody component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeGridHead

#### Props
Properties for the CalendarRangeGridHead component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeGridRow

#### Props
Properties for the CalendarRangeGridRow component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeHeadCell

#### Props
Properties for the CalendarRangeHeadCell component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeHeader

#### Props
Properties for the CalendarRangeHeader component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeHeading

#### Props
Properties for the CalendarRangeHeading component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slot Props
Slot properties for the CalendarRangeHeading component.
- `selectedMonth`: No description. (type `number`; required)
- `selectedYear`: No description. (type `number`; required)
- `headingValue`: Heading value exposed in the slot scope. (type `string`; required)
- `yearOptions`: Year options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onYearChange`: Callback invoked when the year changes. (type `(value?: number | undefined) => void`; required)
- `monthOptions`: Month options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onMonthChange`: Callback invoked when the month changes. (type `(value?: number | undefined) => void`; required)

### CalendarRangeNext

#### Props
Properties for the CalendarRangeNext component.
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangePrev

#### Props
Properties for the CalendarRangePrev component.
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CalendarRangeRoot

#### Props
Properties for the CalendarRangeRoot component.
- `defaultValue`: Default value. (type `DateRange`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `allowNonContiguousRanges`: Whether to allow non contiguous ranges. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `maximumDays`: Maximum days. (type `number`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `locale`: Locale. (type `string`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `isDateHighlightable`: Whether a date highlightable. (type `DateMatcher`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `fixedDate`: Fixed date. (type `'start' | 'end'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CalendarRangeRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the CalendarRangeRoot component.
- `default`: Custom content for the default slot. (type `((props: CalendarRangeRootSlotProps) => any) | undefined`)
#### Slot Props
- `date`: Date exposed in the slot scope. (type `Date | import("../../date").DateTimeValue`; required)
- `headingValue`: Heading value exposed in the slot scope. (type `string`; required)
- `placeholder`: Placeholder exposed in the slot scope. (type `Date | import("../../date").DateTimeValue`; required)
- `grid`: Grid exposed in the slot scope. (type `DateGrid<Date>[]`; required)
- `weekDays`: Week days exposed in the slot scope. (type `string[]`; required)
- `weekStartsOn`: Week starts on exposed in the slot scope. (type `number`; required)
- `locale`: Locale exposed in the slot scope. (type `string`; required)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; required)
- `modelValue`: Current model value. (type `DateRange`; required)
- `formatter`: Formatter exposed in the slot scope. (type `Formatter`; required)
- `minValue`: Min value exposed in the slot scope. (type `DateValue | undefined`; required)
- `maxValue`: Max value exposed in the slot scope. (type `DateValue | undefined`; required)
- `disabled`: Whether the component is disabled. (type `boolean`; required)
- `onPlaceholderChange`: Callback invoked when the placeholder changes. (type `(date: DateValue) => void`; required)
- `yearOptions`: Year options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onYearChange`: Callback invoked when the year changes. (type `(value?: number | undefined) => void`; required)
- `monthOptions`: Month options exposed in the slot scope. (type `SelectOptionData<number>[]`; required)
- `onMonthChange`: Callback invoked when the month changes. (type `(value?: number | undefined) => void`; required)

## Notes

### Architecture and benchmark differences

`CalendarRangeRoot` owns the value via `useControllableState` (`DateRange` = `{ start, end }`), keeps the placeholder for grid paging, and delegates grid creation to `useCalendar` (shared with `calendar`). `useCalendarRangeState` derives selected/highlighted state and exposes `isRangeInvalid(start, end)` — a candidate-range validator used both by the derived `data-invalid` state and by `onDateChange` when committing a new range (so a non-contiguous range is rejected based on the candidate, not the previously committed state). `CalendarRangeCellTrigger` is the only interactive piece: it reads the shared context, computes `data-selection-start`/`data-selection-end`/`data-highlighted`/`data-selected`/`data-today`/`data-unavailable`/`data-outside-view`, handles Arrow/Enter/Space keys with `dir`-aware direction (RTL flips ArrowLeft/ArrowRight), and pages to adjacent months when navigation crosses the grid boundary. `CalendarRangeCell` carries `data-in-range` for the days of a committed range, which is what the styled band keys on — a lone start is `data-selected` without a band, so the band can only appear once both ends are picked. Most benchmark libraries ship a monolithic range panel; the headless/styled split, per-part `*Props` passthrough, hover preview, and candidate-range validation are the differentiators.

| Capability                     | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :----------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split          |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Range picking (start + end)    |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Hover range preview            |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| Keyboard grid navigation       |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   ✅   |
| RTL direction reversal         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| `numberOfMonths` grid          |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| `allowNonContiguousRanges`     |    ✅     |     —      |      ✅      |   ✅    |    —     |   —    |
| `maximumDays` cap              |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| `fixedDate` pinned end         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| `minValue`/`maxValue` bounds   |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isDateDisabled` / unavailable |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Month/year Select controls     |    ✅     |     ✅     |      ✅      |    —    |    —     |   —    |
| Candidate-range validation     |    ✅     |     —      |      —       |    —    |    —     |   —    |

### Cautions

- The value is a `DateRange` — `{ start, end }` of `DateValue`s (native `Date` at local midnight), never strings.
- A range with gaps is rejected by default (the second click restarts the range at the clicked day); pass `allowNonContiguousRanges` to allow gaps.
- `defaultValue`/`defaultPlaceholder` are read on mount only — use `v-model` for external control.
- `isDateDisabled` and `isDateUnavailable` differ: disabled dates are unselectable by policy, unavailable dates are additionally marked visually (`line-through` in the default style).
- `fixedDate` pins one end: with `fixedDate="start"` re-picking always updates the end; with `fixedDate="end"` re-picking always updates the start.
- The prev/next `aria-label`s default to locale messages; override per button through `prevProps`/`nextProps`.
- Each day button's `aria-label` defaults to the full localized date; override it per cell through `cellTriggerProps`.
- The range band is cell-level: days inside a committed range carry `data-in-range` (a lone start is `data-selected` only, so it draws no band). Key custom band styling on `ui.cell` + `data-in-range`, not on `data-selected`.

## FAQ

### How do I select a range?

Click the start date, then the end date — in either order. While picking the end, the hovered span is previewed with the highlighted state. The range is emitted as `{ start, end }` via `v-model`.

### How do I prevent ranges that span unavailable days?

Keep `allowNonContiguousRanges` off (default): when the second click would create a range crossing a disabled or unavailable day, the selection is rejected and restarts at the clicked day. Set `allowNonContiguousRanges` to allow gaps.

### How do I cap the range length?

Pass `maximumDays` (inclusive). Clicking an end that exceeds the cap restarts the selection at the clicked day.

### How do I keep one end fixed while re-picking?

Pass `fixedDate="start"` (or `"end"`). Clicking any day updates the other end, and clicking before/after the pinned end sorts the result automatically.

### How do I build a popup range picker?

Use `SDateRangePicker`, which composes `CalendarRangeCompact` inside a popover trigger. Use `SCalendarRange` standalone when the calendar surface is always visible.

## Card

- Page URL: /components/card
- Markdown URL: /components/card.md
- Description: A container that groups related content and actions into a bordered, shadowed surface. SCard is a UI-only composition over the admitted collapsible primitives (CollapsibleRoot/CollapsibleContent/CollapsibleTrigger) plus its own header/title/description/footer chrome, styled by the cardVariants recipe (8 slots, 6 sizes, scrollable/split flags).

# Card

## Overview

A container that groups related content and actions into a bordered, shadowed surface. `SCard` is a **UI-only** component: it composes the admitted headless `collapsible` primitives (`CollapsibleRoot` / `CollapsibleContent` / `CollapsibleTrigger`) for the only real behavior a card has — collapsing — and owns its own header/title/description/footer chrome, styled by the `cardVariants` recipe (8 slots, 6 sizes, `scrollable`/`split` flags).

Use it for dashboards, profile blocks, settings panels, or any content that benefits from a titled, sectioned container. Prefer `list` or `table` for repetitive data rows, and `popover`/`dialog` for floating or modal surfaces.

The card is **collapsible by default** — the content area animates open/closed and can be driven with `v-model:open`. There is no headless `card` family: the chrome nodes are presentation-only, so they live in the UI layer and keep `data-soybean-card-*` attributes for styling and tests.

## Usage

Usage examples for card are rendered on the site.

## Features

- 🧩 UI-only over admitted primitives — the collapsible behavior comes from the headless `collapsible` family; `SCard` owns the chrome and injects the `cardVariants` classes through `provideCollapsibleUi`
- 🧱 Composite structure — `header`/`title`/`description`/`content`/`footer` plus `title-leading`/`title-trailing`/`extra` slots
- 🔽 Collapsible — the content animates open/closed (`CollapsibleRoot`/`CollapsibleContent`), controlled with `v-model:open`/`defaultOpen`
- ➗ Split sections — `split` adds `divide-y` dividers between title/content/footer
- 📜 Scrollable content — `scrollable` makes the content area scroll when it exceeds the card height
- 🎨 6 sizes — xs–2xl `size` matching `ThemeSize`
- 🎛️ Per-part control — `title`/`description` as props or slots; `headerProps`/`contentProps`/`footerProps`/`titleProps` forwarded to each part
- ♿ Accessible by default — title renders as a real `<h3>`, the collapsible trigger exposes `aria-expanded`, and `axe-core` reports zero violations

## Component family

- `SCard` — the entry component; renders `CollapsibleRoot` (`defaultOpen: true`) plus the `header` / `title-root` / `title` / `description` / `content` / `footer` nodes, and feeds the `cardVariants` recipe to `provideCollapsibleUi`
- `SCardCollapsibleTrigger` — the collapsible trigger bound to the card state; renders a chevron `SButtonIcon` by default and exposes the `open` state through its slot props

## Demos

Interactive demos for card are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (9): Card, CardCollapsibleTrigger, CardContent, CardDescription, CardFooter, CardHeader, CardRoot, CardTitle, CardTitleRoot.

### Card

#### Props
Properties for the Card component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CardUi>`; optional)
- `scrollable`: If true, the content will be scrollable when the root has height and content is taller than the root (type `boolean`; default `false`; optional)
- `split`: If true, the card will add divider between title and content and footer (type `boolean`; default `false`; optional)
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CardHeaderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `CardContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `CardFooterProps`; optional)
- `titleRootProps`: Properties forwarded to the title root element. (type `CardTitleRootProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `CardTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `CardDescriptionProps`; optional)
- `defaultOpen`: The open state of the collapsible when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the collapsible. Can be bound with `v-model`. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the collapsible. (type `boolean`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Card component.
- `update:open`: Event handler called when the open state of the collapsible changes. (type `[value: boolean]`; parameters `value: boolean`)
#### Slots
Slots for the Card component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `header`: Custom content for the header slot. (type `(() => any) | undefined`)
- `title`: Custom content for the title slot. (type `(() => any) | undefined`)
- `title-leading`: Custom content for the title leading slot. (type `(() => any) | undefined`)
- `title-trailing`: Custom content for the title trailing slot. (type `(() => any) | undefined`)
- `extra`: Custom content for the extra slot. (type `(() => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `(() => any) | undefined`)
- `description`: Custom content for the description slot. (type `(() => any) | undefined`)

### CardCollapsibleTrigger

#### Props
Properties for the card collapsible trigger element.
- `disabledCollapsible`: When `true`, prevents the user from toggling the collapsible. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CardContent

#### Props
Properties for the card content element.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CardDescription

- No documented props, emits, slots, or slot props were available.

### CardFooter

- No documented props, emits, slots, or slot props were available.

### CardHeader

- No documented props, emits, slots, or slot props were available.

### CardRoot

#### Props
Properties for the card root element. The card composes `CollapsibleRoot`, so the
collapsible open/disabled contract is shared with the collapsible family.
- `defaultOpen`: The open state of the collapsible when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the collapsible. Can be bound with `v-model`. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the collapsible. (type `boolean`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the card root element.
- `update:open`: Event handler called when the open state of the collapsible changes. (type `[value: boolean]`; parameters `value: boolean`)

### CardTitle

- No documented props, emits, slots, or slot props were available.

### CardTitleRoot

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`Card` is the **UI-only** exemplar of the headless admission rule: its only real logic is collapsing, which the admitted `collapsible` family already provides, so no headless `card` family exists. `SCard` owns the structure orchestration (header/footer visibility, default title/description) and hands the recipe's `root` / `content` / `trigger` slots to `provideCollapsibleUi`, so `CollapsibleRoot` / `CollapsibleContent` / `CollapsibleTrigger` resolve their own classes from `cardVariants`. This mirrors shadcn/ui's composition-first approach, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled card with `title`/`extra`/`actions` props. SoybeanUI makes the card **collapsible by default** through the `CollapsibleRoot` primitive, a deliberate extension most libraries do not offer on a card; `split` and `scrollable` are toggled via recipe variants rather than layout props.

| Capability                   | SoybeanUI | shadcn/ui | Ant Design Card | Element Plus Card | Mantine Card | Naive UI Card |
| :--------------------------- | :-------: | :-------: | :-------------: | :---------------: | :----------: | :-----------: |
| Headless/styled split        |    ✅     |    ✅     |        —        |         —         |      —       |       —       |
| Header / title / description |    ✅     |    ✅     |       ✅        |        ✅         |      ✅      |      ✅       |
| Footer                       |    ✅     |    ✅     |       ✅        |        ✅         |      ✅      |      ✅       |
| Extra (actions) slot         |    ✅     |     —     |       ✅        |        ✅         |      ✅      |      ✅       |
| Collapsible content          |    ✅     |     —     |        —        |         —         |      —       |       —       |
| Split / divider              |    ✅     |     —     |       ✅        |        ✅         |      ✅      |       —       |
| Scrollable content           |    ✅     |     —     |       ✅        |         —         |      —       |      ✅       |
| Size variants (6)            |    ✅     |     —     |       ✅        |        ✅         |      ✅      |      ✅       |
| Per-part `*Props` channels   |    ✅     |    ✅     |        —        |         —         |      —       |       —       |

`—` = unsupported or a different interaction model.

### Cautions

- The card is collapsible and defaults to open (`defaultOpen: true`). When collapsed, the content (and footer) is removed from the flow; footer visibility depends on the open state.
- The title renders as a fixed `<h3>`. If your page's heading hierarchy differs, wrap or restyle the title so it does not skip levels.
- The content node carries `tabindex="-1"` so a scrollable body can receive programmatic focus; it is not an interactive control by itself. Override it through `contentProps`.
- `SCardCollapsibleTrigger` renders an icon-only button, so pass `aria-label` (e.g. `aria-label="Toggle card content"`) to give it an accessible name.
- `split` applies `divide-y`; combine it with a `size` to control the vertical rhythm. `scrollable` only takes effect when the card has a constrained height.
- The content padding adjusts automatically based on `data-header-visible`/`data-footer-visible` (and the collapsible `data-state`) so a bare content-only card still looks balanced.

### Roadmap

No blocking gaps identified for the core card API. A `card`-level interactive action bar / `CardActions` shortcut and hover-lift style variants are evaluated enhancements tracked in `docs/roadmap.md`.

## FAQ

### How do I build a card with a title and description?

Pass `title`/`description` props (or the matching slots):

```vue

  <p>Body content</p>

```

### How do I add actions to the header?

Use the `extra` slot (or `title-leading`/`title-trailing` around the title):

```vue

  <template #extra><SButton variant="pure">Edit</SButton></template>
  <p>Body content</p>

```

### How do I make a collapsible card?

Bind `open` with `v-model` (or set `default-open`):

```vue

  <p>This content can collapse.</p>

```

### How do I make the content scrollable?

Keep the card height constrained and set `scrollable`:

```vue

  <p v-for="i in 50" :key="i">Row {{ i }}</p>

```

### How do I split the sections with dividers?

Set `split` to add `divide-y` dividers between header/content/footer:

```vue

  <template #footer><SButton>Save</SButton></template>
  <p>Body content</p>

```

## Carousel

- Page URL: /components/carousel
- Markdown URL: /components/carousel.md
- Description: A carousel built on top of Embla Carousel that lets users browse a sequence of content (images, cards, banners, etc.) horizontally or vertically in a constrained space. SCarousel combines a CarouselRoot-family of headless primitives (zero styles) with the carouselVariants style recipe (8 slots: root/content/container/item/control/navigation/previous/next, 6 sizes × 2 orientations).

# Carousel

## Overview

A carousel built on top of Embla Carousel that lets users browse a sequence of content (images, cards, banners, etc.) horizontally or vertically in a constrained space. `SCarousel` combines a `CarouselRoot`-family of headless primitives (zero styles) with the `carouselVariants` style recipe (8 slots: root/content/container/item/control/navigation/previous/next, 6 sizes × 2 orientations).

Use it for image galleries, product/article carousels, banner rotators, or any "one viewport at a time, paged back and forth" content. Prefer `list` or `layout` for static grids and masonry; prefer `tree`/`list` with `virtualizer` for drag-sorting or long virtual lists instead of a carousel.

`SCarousel` aggregates the primitives through `CarouselCompact` and exposes a `slides`-driven API. For fully custom compositions, fall back to the headless `CarouselRoot`/`CarouselContent`/`CarouselContainer`/`CarouselItem`/`CarouselControl`/`CarouselNavigation`/`CarouselPrevious`/`CarouselNext` primitives.

## Usage

Usage examples for carousel are rendered on the site.

## Features

- 🧩 Headless/styled split — `CarouselCompact` aggregates the 8 primitives and exposes 7 `*Props` channels (content/container/item/control/navigation/previous/next); `SCarousel` only injects styles and forwards slots/events
- 🧭 Horizontal / vertical — `orientation` switches the slide axis, the arrow-key navigation axis and the layout direction
- 🌐 Direction-aware — `dir` is forwarded to Embla and swaps the `ArrowLeft`/`ArrowRight` key semantics under RTL
- ⌨️ Keyboard reachable — when the root region is focused, arrow keys page back and forth; `previous`/`next` auto-`disabled` at the boundaries
- ♿ Accessible by default — root `role="region"` + `aria-roledescription="carousel"`, each slide `role="group"` + `aria-roledescription="slide"`; button default content and `aria-label` fallbacks are localized via `useLocaleMessages`
- 🎛️ Controlled / uncontrolled — pass Embla configuration directly through `options` (`loop`, `align`, `dragFree`, …); the root slot exposes `scrollTo`/`scrollNext`/`scrollPrev`/`selectedIndex`/`scrollSnaps`/`progress`
- 🎨 8-slot styling — root/content/container/item/control/navigation/previous/next with 6 sizes (xs–2xl) and a `floatNav` floating-navigation layout
- 🧩 Fully customizable — per-slot `ui` overrides, root `class` override, `slides`-driven data with `item`/`control`/`previous`/`next` slots replacing the defaults

## Component family

- `SCarousel` (styled) — the entry wrapper; `carouselVariants` recipe with dynamic slot forwarding and `useForwardListeners` event merging
- `CarouselRoot` (headless) — the state owner: initializes/destroys the Embla instance via `useEmblaCarousel`, derives `canScrollNext`/`canScrollPrev`/`selectedIndex`/`scrollSnaps`/`progress`; renders `role="region"`, `data-orientation`, the localized `aria-label` fallback and arrow-key navigation
- `CarouselContent` (headless) — the viewport; holds the Embla root element reference and generates the `id` shared with the nav buttons
- `CarouselContainer` (headless) — the sliding track; hosts every `CarouselItem`
- `CarouselItem` (headless) — a single slide; `role="group"` + `aria-roledescription="slide"`
- `CarouselControl` (headless) — the controls container; hosts the navigation or custom controls
- `CarouselNavigation` (headless) — the container for the previous/next buttons
- `CarouselPrevious` / `CarouselNext` (headless) — `Button`-based prev/next buttons; default icon rendered via `Icon`, default text visually hidden (`VisuallyHidden`) and localized
- `CarouselCompact` (headless) — the aggregated composite; iterates `slides` into `CarouselItem`, exposing `item`/`control`/`previous`/`next` slots

## Demos

Interactive demos for carousel are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (10): Carousel, CarouselCompact, CarouselContainer, CarouselContent, CarouselControl, CarouselItem, CarouselNavigation, CarouselNext, CarouselPrevious, CarouselRoot.

### Carousel

#### Props
Properties for the Carousel component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CarouselUi>`; optional)
- `size`: The size of the carousel, which determines the spacing and sizing of its elements. (type `ThemeSize`; optional)
- `floatNav`: Whether to use floating navigation, which positions the navigation controls outside of the carousel content and allows them to float over the content. This is useful for carousels with a lot of content or when you want to maximize the space available for the slides. (type `boolean`; optional)
- `slides`: Slides to be rendered in the carousel. (type `T[]`; required)
- `contentProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselContentProps`; optional)
- `containerProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselContainerProps`; optional)
- `itemProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselItemProps`; optional)
- `controlProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselControlProps`; optional)
- `navigationProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselNavigationProps`; optional)
- `previousProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselPreviousProps`; optional)
- `nextProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselNextProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `options`: Options. (type `Partial<import("../../../node_modules/embla-carousel/esm/components/Options").OptionsType>`; optional)
- `plugins`: Plugins. (type `import("embla-carousel").CreatePluginType<import("../../../node_modules/embla-carousel/esm/components/Plugins").Loose...`; optional)
#### Emits
Events for the Carousel component.
- `init`: Emitted when init occurs. (type `[carousel: EmblaCarouselType]`; parameters `carousel: EmblaCarouselType`)
#### Slots
Slots for the Carousel component.
- `item`: Default slot for the carousel component, which can be used to render custom content in the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps & { slide: T; index: number; selected: boolean; }) => any) | undefined`)
- `control`: Control slot for the carousel component, which can be used to render custom controls for the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps) => any) | undefined`)
- `previous`: Navigation slot for the carousel component, which can be used to render custom navigation for the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps) => any) | undefined`)
- `next`: Next slot for the carousel component, which can be used to render custom next controls for the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps) => any) | undefined`)

### CarouselCompact

#### Props
Properties for the CarouselCompact component.
- `slides`: Slides to be rendered in the carousel. (type `T[]`; required)
- `contentProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselContentProps`; optional)
- `containerProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselContainerProps`; optional)
- `itemProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselItemProps`; optional)
- `controlProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselControlProps`; optional)
- `navigationProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselNavigationProps`; optional)
- `previousProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselPreviousProps`; optional)
- `nextProps`: Per-slot properties for the component, allowing you to pass props directly to the sub components without needing to use the `v-slot` API. This is useful for quickly customizing the sub components without needing to use the full flexibility of slots. (type `CarouselNextProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `options`: Options. (type `Partial<import("../../../node_modules/embla-carousel/esm/components/Options").OptionsType>`; optional)
- `plugins`: Plugins. (type `import("embla-carousel").CreatePluginType<import("../../../node_modules/embla-carousel/esm/components/Plugins").Loose...`; optional)
#### Emits
Events for the CarouselCompact component.
- `init`: Emitted when init occurs. (type `[carousel: EmblaCarouselType]`; parameters `carousel: EmblaCarouselType`)
#### Slots
Slots for the CarouselCompact component.
- `item`: Default slot for the carousel component, which can be used to render custom content in the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps & { slide: T; index: number; selected: boolean; }) => any) | undefined`)
- `control`: Control slot for the carousel component, which can be used to render custom controls for the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps) => any) | undefined`)
- `previous`: Navigation slot for the carousel component, which can be used to render custom navigation for the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps) => any) | undefined`)
- `next`: Next slot for the carousel component, which can be used to render custom next controls for the carousel. The slot props include all the necessary information and methods to control the carousel, such as the carousel instance, whether it can scroll next or prev, the selected index, scroll snaps, progress, and methods to scroll next, prev, or to a specific index. (type `((props: CarouselRootSlotProps) => any) | undefined`)

### CarouselContainer

- No documented props, emits, slots, or slot props were available.

### CarouselContent

- No documented props, emits, slots, or slot props were available.

### CarouselControl

- No documented props, emits, slots, or slot props were available.

### CarouselItem

- No documented props, emits, slots, or slot props were available.

### CarouselNavigation

- No documented props, emits, slots, or slot props were available.

### CarouselNext

#### Props
Properties for the CarouselNext component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CarouselPrevious

#### Props
Properties for the CarouselPrevious component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CarouselRoot

#### Props
Properties for the CarouselRoot component.
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `options`: Options. (type `Partial<import("../../../node_modules/embla-carousel/esm/components/Options").OptionsType>`; optional)
- `plugins`: Plugins. (type `import("embla-carousel").CreatePluginType<import("../../../node_modules/embla-carousel/esm/components/Plugins").Loose...`; optional)
#### Emits
Events for the CarouselRoot component.
- `init`: Emitted when init occurs. (type `[carousel: EmblaCarouselType]`; parameters `carousel: EmblaCarouselType`)
#### Slots
Slots for the CarouselRoot component.
- `default`: No description. (type `((props: CarouselRootSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the CarouselRoot component.
- `carousel`: No description. (type `EmblaCarouselType | undefined`; required)
- `canScrollNext`: No description. (type `boolean`; required)
- `canScrollPrev`: No description. (type `boolean`; required)
- `selectedIndex`: No description. (type `number`; required)
- `scrollSnaps`: No description. (type `number[]`; required)
- `progress`: No description. (type `number`; required)
- `scrollNext`: No description. (type `() => void`; required)
- `scrollPrev`: No description. (type `() => void`; required)
- `scrollTo`: No description. (type `(index: number, jump?: boolean) => void`; required)

## Notes

### Architecture and benchmark differences

`CarouselRoot` owns the full Embla instance lifecycle (init/re-init/destroy, `select`/`reInit` events syncing scroll state) while every primitive stays style-free and only the UI wrapper injects the `carouselVariants` classes. This mirrors shadcn/ui's headless/styled split, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a carousel as a single styled component with configuration props. SoybeanUI deliberately routes behaviors such as `autoplay`, `loop` and `align` through `options` into Embla's plugin system instead of declaring them as top-level props, keeping the API lean and letting users plug in any Embla plugin. The prev/next buttons default to `disabled` at the boundaries, derived from `canScrollNext`/`canScrollPrev` rather than depending on the `loop` configuration.

| Capability                           | SoybeanUI | shadcn/ui | Ant Design Carousel | Element Plus Carousel | Mantine Carousel | Naive UI Carousel |
| :----------------------------------- | :-------: | :-------: | :-----------------: | :-------------------: | :--------------: | :---------------: |
| Headless/styled split                |    ✅     |    ✅     |          —          |           —           |        —         |         —         |
| Horizontal / vertical orientation    |    ✅     |     —     |         ✅          |          ✅           |        ✅        |        ✅         |
| Direction-aware (RTL)                |    ✅     |    ✅     |         ✅          |           —           |        —         |         —         |
| Arrow-key navigation                 |    ✅     |     —     |         ✅          |          ✅           |        —         |         —         |
| Localized button/region `aria-label` |    ✅     |     —     |          —          |           —           |        —         |         —         |
| `autoplay` / `loop` / alignment      |  options  |  options  |        props        |         props         |      props       |       props       |
| Composite with per-part props        |    ✅     |    ✅     |          —          |           —           |        —         |         —         |

`—` = unsupported or a different interaction model (AntD/Element Plus/Mantine/Naive UI are single-package config-driven carousels; shadcn/ui's Carousel block is a copy-source headless composition but hardcodes the nav button text and lacks arrow-key navigation).

### Cautions

- `SCarousel` depends on Embla's layout engine; under SSR the first paint cannot measure real sizes, so scroll snapping and `canScrollNext`/`canScrollPrev` are only correct after client mount. Do not rely on the server-rendered initial `selectedIndex`/`progress`.
- `options` and `plugins` are reactive: changing them `reInit`s the Embla instance. Passing a fresh object literal on every render triggers unnecessary rebuilds — keep a stable `ref`/`shallowRef` reference.
- `floatNav: true` (the default) absolutely positions the prev/next buttons to the sides of the content; in a narrow container they may overflow the visible area. Use `float-nav="false"` or override the navigation positioning via `ui`.
- The default prev/next icons are `lucide:arrow-left`/`lucide:arrow-right` rendered through the ConfigProvider `iconRender`; without one, the `Icon` component renders nothing and only the `VisuallyHidden` text carries the accessible name.
- `CarouselItem` keys are derived from item order (`index`), so reordering `slides` does not reuse component instances — keep the order stable when slide content is stateful.

## FAQ

### How do I enable autoplay?

Configure `{ loop: true }` in `options` and pass Embla's `Autoplay` plugin through `plugins`:

```vue

```

### How do I render custom dots?

Use the `control` slot and read `scrollSnaps`/`selectedIndex` from the slot props, jumping with `scrollTo`:

```vue
<template #control="{ scrollSnaps, selectedIndex, scrollTo }">
  <div v-for="(_, index) in scrollSnaps" :key="index" @click="scrollTo(index)" />
</template>
```

### How do I show progress or page numbers?

The `progress` slot prop is a 0–100 scroll percentage (0 on the first screen) you can feed to `SProgress`; page numbers come from `selectedIndex + 1` over `scrollSnaps.length` (see the `06-progress` and `05-snap` demos).

### How do I show multiple slides at once?

Override the `item` slot's `basis` via `ui` (e.g. `basis-1/2 md:basis-1/3`) and tune snapping with `options.align`/`containScroll` (see the `04-multi` demo).

### How do I localize the prev/next buttons and region name?

The button text and region `aria-label` fallback follow the ConfigProvider locale (`carousel.previous` / `carousel.next` / `carousel.ariaLabel`); override per instance with `aria-label` when needed.

### How do I replace the default buttons?

Use the `previous`/`next` or `control` slots to render custom controls — the slot props include `canScrollNext`/`canScrollPrev` and `scrollNext`/`scrollPrev`.

## Cascader

- Page URL: /components/cascader
- Markdown URL: /components/cascader.md
- Description: A cascader for selecting values from hierarchical tree data. It renders a linked multi-column panel and supports single/multiple selection, full-path value mode, parent-child check-state propagation, local filtering and remote search, lazy loading of children, and virtual scrolling for large datasets. Use it when options are organized as a tree and selection must happen level by level; for flat option lists, prefer SSelect or SCombobox.

# Cascader

## Overview

A cascader for selecting values from hierarchical tree data. It renders a linked multi-column panel and supports single/multiple selection, full-path value mode, parent-child check-state propagation, local filtering and remote search, lazy loading of children, and virtual scrolling for large datasets. Use it when options are organized as a tree and selection must happen level by level; for flat option lists, prefer `SSelect` or `SCombobox`.

## Usage

Usage examples for cascader are rendered on the site.

## Features

- 🗂 Linked multi-column panel — the path unfolds one level per column
- ☑️ Single or multiple selection with cascading parent-child check states (`showCheckedStrategy`: child / parent)
- 🛤 Full-path value mode (`pathMode`) — the model value carries the complete value/label path
- ⏳ Data loading — lazy children (`loadChildren`), debounced remote search (`searchDelay`), local filtering (`filter`) with a localized empty state
- 📜 Built-in per-column virtual scrolling (`virtualScroll`, configurable `itemSize` / `height`)
- ⌨️ Full keyboard navigation — Arrow keys move across columns, Enter selects, plus click/hover expand
- ♿ WAI-ARIA tree semantics — trigger `role="combobox"` + `aria-haspopup="tree"`, option `role="treeitem"`, axe-clean when open
- 🎨 16 recipe slots and 7 size variants via `cascaderVariants`

## Demos

Interactive demos for cascader are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (17): Cascader, CascaderArrow, CascaderClear, CascaderCompact, CascaderCompactOption, CascaderCompactTag, CascaderCompactTriggerValue, CascaderContent, CascaderEmpty, CascaderMenu, CascaderOption, CascaderPortal, CascaderRoot, CascaderSearchInput, CascaderTags, CascaderTrigger, CascaderValue.

### Cascader

#### Props
Properties for the Cascader component.
- `class`: the class of cascader trigger (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CascaderUi>`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `showArrow`: When `true`, the arrow icon is rendered. (type `boolean`; default `true`; optional)
- `placement`: The placement of the content. (type `import("@/index").Placement`; optional)
- `triggerProps`: Properties forwarded to the trigger part. (type `CascaderTriggerProps`; optional)
- `valueProps`: Properties forwarded to the value part. (type `CascaderValueProps`; optional)
- `searchInputProps`: Properties forwarded to the search input part. (type `CascaderSearchInputProps`; optional)
- `portalProps`: Properties forwarded to the portal part. (type `PortalProps`; optional)
- `contentProps`: Properties forwarded to the content part. (type `CascaderContentProps`; optional)
- `menuProps`: Properties forwarded to every menu part. (type `CascaderMenuProps`; optional)
- `optionProps`: Properties forwarded to every option part. (type `Partial<CascaderOptionProps<T>>`; optional)
- `emptyProps`: Properties forwarded to the empty part. (type `CascaderEmptyProps`; optional)
- `emptyLabel`: The text shown in the empty state. (type `string`; default `The locale message`; optional)
- `clearLabel`: The accessible label of the clear button. (type `string`; default `The locale message`; optional)
- `arrowProps`: Properties forwarded to the arrow part. (type `PopperArrowProps`; optional)
- `modelValue`: The controlled value of the selected node(s). Can be bound with `v-model`. (type `CascaderValueType<T, M, P>`; optional)
- `defaultValue`: The default value of the selected node(s). (type `CascaderValueType<T, M, P>`; optional)
- `multiple`: When `true`, multiple nodes can be selected. (type `M`; optional)
- `pathMode`: When `true`, the model value is the full path array(s) instead of the node value(s). (type `P`; default `false`; optional)
- `options`: Options of the cascader. (type `CascaderOptionData<T>[]`; optional)
- `fieldKeys`: Field keys used to extract the option fields. (type `CascaderFieldKeys`; optional)
- `open`: The controlled open state of the Cascader. Can be bound as `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the cascader when it is initially rendered. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the Cascader. (type `boolean`; optional)
- `clearable`: When `true`, the value can be cleared by the clear button. (type `boolean`; optional)
- `expandTrigger`: The trigger to expand the children of a node. (type `'click' | 'hover'`; default `'click'`; optional)
- `checkStrictly`: When `false`, only leaf nodes can be selected (single) or the parent-children check states are linked (multiple). When `true`, any node can be selected independently. (type `boolean`; default `false`; optional)
- `showCheckedStrategy`: The strategy used to collect and display checked nodes in multiple mode. - `child`: collect the leaves of the checked region. - `parent`: collect the topmost checked nodes (fold fully-checked subtrees into parents). (type `'child' | 'parent'`; default `'child'`; optional)
- `separator`: The separator used to join the path labels. (type `string`; default `' / '`; optional)
- `filterable`: When `true`, the trigger becomes a search input and the panel shows flat filtered results. (type `boolean`; optional)
- `filter`: Custom filter function used in local filtering mode. The default performs a case-insensitive `includes` match against every label of the path. (type `((pattern: string, option: CascaderOptionData<T>, path: string[]) => boolean)`; optional)
- `remote`: When `true`, the panel loads its options from `onSearch` instead of filtering locally. (type `boolean`; optional)
- `onSearch`: Async search function used in remote mode. Returns the flat options for the keyword. (type `((pattern: string) => Promise<CascaderOptionData<T>[]>)`; optional)
- `searchDelay`: Debounce delay in milliseconds for filtering and remote search. (type `number`; default `300`; optional)
- `lazy`: When `true`, children of a node are loaded asynchronously via `onLoad`. (type `boolean`; optional)
- `onLoad`: Async function used to load the children of a node when `lazy` is `true`. (type `((option: CascaderNode<T>) => Promise<CascaderOptionData<T>[]>)`; optional)
- `virtualScroll`: When `true`, only the visible rows of each column are rendered. (type `boolean`; optional)
- `itemSize`: The fixed height of a row used by virtual scrolling. (type `number`; default `34`; optional)
- `height`: The height of the panel used by virtual scrolling. (type `number`; default `204`; optional)
- `dir`: The reading direction of the component. (type `Direction`; optional)
- `placeholder`: The content shown when no node is selected. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Cascader component.
- `update:modelValue`: Event handler called when the value of the cascader changes. Can be bound as `v-model`. (type `[value: CascaderValueType<T, M, P>]`; parameters `value: CascaderValueType<T, M, P>`)
- `update:open`: Event handler called when the open state of the cascader changes. Can be bound as `v-model:open`. (type `[value: boolean]`; parameters `value: boolean`)
- `change`: Event handler called when the value changes, with the selected nodes. (type `[value: CascaderValueType<T, M, P> | undefined, nodes: CascaderNode<T>[]]`; parameters `value: CascaderValueType<T, M, P> | undefined, nodes: CascaderNode<T>[]`)
- `clear`: Event handler called when the selection is cleared. (type `[]`)
- `loaded`: Event handler called when the children of a node have been loaded (lazy mode). (type `[node: CascaderNode<T>]`; parameters `node: CascaderNode<T>`)
- `closeAutoFocus`: Emitted when close auto focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `placed`: Emitted when the content is placed. (type `[]`)
#### Slots
Slots for the Cascader component.
- `trigger-icon`: Custom content for the trigger icon (arrow). (type `(() => any) | undefined`)
- `trigger-value`: Custom content for the trigger value. (type `((props: CascaderCompactTriggerValueSlotProps<T, M, P>) => any) | undefined`)
- `search-input`: Custom content for the search input. (type `(() => any) | undefined`)
- `option`: Custom content for a single option. (type `((props: CascaderCompactOptionSlotProps<T>) => any) | undefined`)
- `tag`: Custom content for a tag in multiple mode. (type `((props: CascaderCompactTagSlotProps<T>) => any) | undefined`)
- `empty`: Custom content for the empty state. (type `(() => any) | undefined`)

### CascaderArrow

- No documented props, emits, slots, or slot props were available.

### CascaderClear

#### Props
Properties for the CascaderClear component.
- `ariaLabel`: The accessible label of the clear button. (type `string`; default `'清除'`; optional)

### CascaderCompact

#### Props
Properties for the CascaderCompact component.
- `showArrow`: When `true`, the arrow icon is rendered. (type `boolean`; default `true`; optional)
- `placement`: The placement of the content. (type `import("@/index").Placement`; optional)
- `triggerProps`: Properties forwarded to the trigger part. (type `CascaderTriggerProps`; optional)
- `valueProps`: Properties forwarded to the value part. (type `CascaderValueProps`; optional)
- `searchInputProps`: Properties forwarded to the search input part. (type `CascaderSearchInputProps`; optional)
- `portalProps`: Properties forwarded to the portal part. (type `PortalProps`; optional)
- `contentProps`: Properties forwarded to the content part. (type `CascaderContentProps`; optional)
- `menuProps`: Properties forwarded to every menu part. (type `CascaderMenuProps`; optional)
- `optionProps`: Properties forwarded to every option part. (type `Partial<CascaderOptionProps<T>>`; optional)
- `emptyProps`: Properties forwarded to the empty part. (type `CascaderEmptyProps`; optional)
- `emptyLabel`: The text shown in the empty state. (type `string`; default `The locale message`; optional)
- `clearLabel`: The accessible label of the clear button. (type `string`; default `The locale message`; optional)
- `arrowProps`: Properties forwarded to the arrow part. (type `PopperArrowProps`; optional)
- `modelValue`: The controlled value of the selected node(s). Can be bound with `v-model`. (type `CascaderValueType<T, M, P>`; optional)
- `defaultValue`: The default value of the selected node(s). (type `CascaderValueType<T, M, P>`; optional)
- `multiple`: When `true`, multiple nodes can be selected. (type `M`; optional)
- `pathMode`: When `true`, the model value is the full path array(s) instead of the node value(s). (type `P`; default `false`; optional)
- `options`: Options of the cascader. (type `CascaderOptionData<T>[]`; optional)
- `fieldKeys`: Field keys used to extract the option fields. (type `CascaderFieldKeys`; optional)
- `open`: The controlled open state of the Cascader. Can be bound as `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the cascader when it is initially rendered. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the Cascader. (type `boolean`; optional)
- `clearable`: When `true`, the value can be cleared by the clear button. (type `boolean`; optional)
- `expandTrigger`: The trigger to expand the children of a node. (type `'click' | 'hover'`; default `'click'`; optional)
- `checkStrictly`: When `false`, only leaf nodes can be selected (single) or the parent-children check states are linked (multiple). When `true`, any node can be selected independently. (type `boolean`; default `false`; optional)
- `showCheckedStrategy`: The strategy used to collect and display checked nodes in multiple mode. - `child`: collect the leaves of the checked region. - `parent`: collect the topmost checked nodes (fold fully-checked subtrees into parents). (type `'child' | 'parent'`; default `'child'`; optional)
- `separator`: The separator used to join the path labels. (type `string`; default `' / '`; optional)
- `filterable`: When `true`, the trigger becomes a search input and the panel shows flat filtered results. (type `boolean`; optional)
- `filter`: Custom filter function used in local filtering mode. The default performs a case-insensitive `includes` match against every label of the path. (type `((pattern: string, option: CascaderOptionData<T>, path: string[]) => boolean)`; optional)
- `remote`: When `true`, the panel loads its options from `onSearch` instead of filtering locally. (type `boolean`; optional)
- `onSearch`: Async search function used in remote mode. Returns the flat options for the keyword. (type `((pattern: string) => Promise<CascaderOptionData<T>[]>)`; optional)
- `searchDelay`: Debounce delay in milliseconds for filtering and remote search. (type `number`; default `300`; optional)
- `lazy`: When `true`, children of a node are loaded asynchronously via `onLoad`. (type `boolean`; optional)
- `onLoad`: Async function used to load the children of a node when `lazy` is `true`. (type `((option: CascaderNode<T>) => Promise<CascaderOptionData<T>[]>)`; optional)
- `virtualScroll`: When `true`, only the visible rows of each column are rendered. (type `boolean`; optional)
- `itemSize`: The fixed height of a row used by virtual scrolling. (type `number`; default `34`; optional)
- `height`: The height of the panel used by virtual scrolling. (type `number`; default `204`; optional)
- `dir`: The reading direction of the component. (type `Direction`; optional)
- `placeholder`: The content shown when no node is selected. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CascaderCompact component.
- `update:modelValue`: Event handler called when the value of the cascader changes. Can be bound as `v-model`. (type `[value: CascaderValueType<T, M, P>]`; parameters `value: CascaderValueType<T, M, P>`)
- `update:open`: Event handler called when the open state of the cascader changes. Can be bound as `v-model:open`. (type `[value: boolean]`; parameters `value: boolean`)
- `change`: Event handler called when the value changes, with the selected nodes. (type `[value: CascaderValueType<T, M, P> | undefined, nodes: CascaderNode<T>[]]`; parameters `value: CascaderValueType<T, M, P> | undefined, nodes: CascaderNode<T>[]`)
- `clear`: Event handler called when the selection is cleared. (type `[]`)
- `loaded`: Event handler called when the children of a node have been loaded (lazy mode). (type `[node: CascaderNode<T>]`; parameters `node: CascaderNode<T>`)
- `closeAutoFocus`: Emitted when close auto focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `placed`: Emitted when the content is placed. (type `[]`)
#### Slots
Slots for the CascaderCompact component.
- `trigger-icon`: Custom content for the trigger icon (arrow). (type `(() => any) | undefined`)
- `trigger-value`: Custom content for the trigger value. (type `((props: CascaderCompactTriggerValueSlotProps<T, M, P>) => any) | undefined`)
- `search-input`: Custom content for the search input. (type `(() => any) | undefined`)
- `option`: Custom content for a single option. (type `((props: CascaderCompactOptionSlotProps<T>) => any) | undefined`)
- `tag`: Custom content for a tag in multiple mode. (type `((props: CascaderCompactTagSlotProps<T>) => any) | undefined`)
- `empty`: Custom content for the empty state. (type `(() => any) | undefined`)

### CascaderCompactOption

#### Slot Props
Slot properties for the CascaderCompact option.
- `node`: The node being rendered. (type `CascaderNode<T>`; required)
- `checked`: Whether the node is checked. (type `boolean`; required)
- `indeterminate`: Whether the node is in an indeterminate state. (type `boolean`; required)
- `selected`: Whether the node is the currently selected node (single-select). (type `boolean`; required)
- `highlighted`: Whether the node is currently highlighted. (type `boolean`; required)
- `childSelected`: Whether a descendant of the node is currently selected (breadcrumb emphasis). (type `boolean`; required)
- `loading`: Whether the node is currently loading its children. (type `boolean`; required)
- `expand`: Expands the children column of the node without toggling its selection. (type `() => void`; required)

### CascaderCompactTag

#### Slot Props
Slot properties for the CascaderCompact tag.
- `node`: The node of the tag. (type `CascaderNode<T>`; required)
- `remove`: Removes the tag from the selection. (type `(node: CascaderNode<T>) => void`; required)

### CascaderCompactTriggerValue

#### Slot Props
Slot properties for the CascaderCompact trigger value.
- `modelValue`: Current model value. (type `M extends true ? MultipleCascaderValue<T, P> : SingleCascaderValue<T, P>`; required)
- `selectedLabels`: Labels of the selected nodes. (type `string[]`; required)
- `slotText`: Text shown in the trigger (selected path or placeholder). (type `string`; required)

### CascaderContent

#### Props
Properties for the CascaderContent component.
- `menuProps`: Properties forwarded to every menu part. (type `CascaderMenuProps`; optional)
- `emptyProps`: Properties forwarded to the empty part. (type `CascaderEmptyProps`; optional)
- `open`: Whether the floating layer is open. Drives the positioning lifecycle (`isPositioned` resets when open flips); the positioning primitive itself has no open state, so consumers wire their own open state here. (type `boolean`; default `true`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the anchor to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the anchor. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the anchor. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `false`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the anchor is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the anchor becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `disableOutsidePointerEvents`: When `true`, hover/focus/click interactions will be disabled on elements outside the `DismissableLayer`. Users will need to click twice on outside elements to interact with them: once to close the `DismissableLayer`, and again to trigger the element. (type `boolean`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the CascaderContent component.
- `closeAutoFocus`: Emitted when close auto focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `placed`: Emitted when the content is placed. (type `[]`)

### CascaderEmpty

- No documented props, emits, slots, or slot props were available.

### CascaderMenu

#### Props
Properties for the CascaderMenu component.
- `level`: The depth of the menu column. (type `number`; optional)
- `optionProps`: Properties forwarded to every option part. (type `Partial<CascaderOptionProps<DefinedValue>>`; optional)

### CascaderOption

#### Props
Properties for the CascaderOption component.
- `node`: The node rendered by the option. (type `CascaderNode<T>`; required)
- `index`: The position of the node inside its column. (type `number`; optional)
- `level`: The depth of the column the option belongs to. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CascaderOption component.
- `select`: Event handler called when the node is selected. Can be prevented by calling `event.preventDefault`. (type `[event: CascaderSelectEvent<T>]`; parameters `event: CascaderSelectEvent<T>`)
- `expand`: Event handler called when the node is expanded. Can be prevented by calling `event.preventDefault`. (type `[event: CascaderExpandEvent<T>]`; parameters `event: CascaderExpandEvent<T>`)

### CascaderPortal

#### Props
Alias of the portal props used by the cascader portal part.
- `to`: Vue native teleport component prop `:to` {@link https://vuejs.org/guide/built-ins/teleport.html#basic-usage} (type `string | HTMLElement`; optional)
- `disabled`: Disable teleport and render the component inline {@link https://vuejs.org/guide/built-ins/teleport.html#disabling-teleport} (type `boolean`; optional)
- `defer`: Defer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) {@link https://vuejs.org/guide/built-ins/teleport.html#deferred-teleport} (type `boolean`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)

### CascaderRoot

#### Props
Properties for the CascaderRoot component.
- `modelValue`: The controlled value of the selected node(s). Can be bound with `v-model`. (type `CascaderValueType<T, M, P>`; optional)
- `defaultValue`: The default value of the selected node(s). (type `CascaderValueType<T, M, P>`; optional)
- `multiple`: When `true`, multiple nodes can be selected. (type `M`; optional)
- `pathMode`: When `true`, the model value is the full path array(s) instead of the node value(s). (type `P`; default `false`; optional)
- `options`: Options of the cascader. (type `CascaderOptionData<T>[]`; optional)
- `fieldKeys`: Field keys used to extract the option fields. (type `CascaderFieldKeys`; optional)
- `open`: The controlled open state of the Cascader. Can be bound as `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the cascader when it is initially rendered. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the Cascader. (type `boolean`; optional)
- `clearable`: When `true`, the value can be cleared by the clear button. (type `boolean`; optional)
- `expandTrigger`: The trigger to expand the children of a node. (type `'click' | 'hover'`; default `'click'`; optional)
- `checkStrictly`: When `false`, only leaf nodes can be selected (single) or the parent-children check states are linked (multiple). When `true`, any node can be selected independently. (type `boolean`; default `false`; optional)
- `showCheckedStrategy`: The strategy used to collect and display checked nodes in multiple mode. - `child`: collect the leaves of the checked region. - `parent`: collect the topmost checked nodes (fold fully-checked subtrees into parents). (type `'child' | 'parent'`; default `'child'`; optional)
- `separator`: The separator used to join the path labels. (type `string`; default `' / '`; optional)
- `filterable`: When `true`, the trigger becomes a search input and the panel shows flat filtered results. (type `boolean`; optional)
- `filter`: Custom filter function used in local filtering mode. The default performs a case-insensitive `includes` match against every label of the path. (type `((pattern: string, option: CascaderOptionData<T>, path: string[]) => boolean)`; optional)
- `remote`: When `true`, the panel loads its options from `onSearch` instead of filtering locally. (type `boolean`; optional)
- `onSearch`: Async search function used in remote mode. Returns the flat options for the keyword. (type `((pattern: string) => Promise<CascaderOptionData<T>[]>)`; optional)
- `searchDelay`: Debounce delay in milliseconds for filtering and remote search. (type `number`; default `300`; optional)
- `lazy`: When `true`, children of a node are loaded asynchronously via `onLoad`. (type `boolean`; optional)
- `onLoad`: Async function used to load the children of a node when `lazy` is `true`. (type `((option: CascaderNode<T>) => Promise<CascaderOptionData<T>[]>)`; optional)
- `virtualScroll`: When `true`, only the visible rows of each column are rendered. (type `boolean`; optional)
- `itemSize`: The fixed height of a row used by virtual scrolling. (type `number`; default `34`; optional)
- `height`: The height of the panel used by virtual scrolling. (type `number`; default `204`; optional)
- `dir`: The reading direction of the component. (type `Direction`; optional)
- `placeholder`: The content shown when no node is selected. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CascaderRoot component.
- `update:modelValue`: Event handler called when the value of the cascader changes. Can be bound as `v-model`. (type `[value: CascaderValueType<T, M, P>]`; parameters `value: CascaderValueType<T, M, P>`)
- `update:open`: Event handler called when the open state of the cascader changes. Can be bound as `v-model:open`. (type `[value: boolean]`; parameters `value: boolean`)
- `change`: Event handler called when the value changes, with the selected nodes. (type `[value: CascaderValueType<T, M, P> | undefined, nodes: CascaderNode<T>[]]`; parameters `value: CascaderValueType<T, M, P> | undefined, nodes: CascaderNode<T>[]`)
- `clear`: Event handler called when the selection is cleared. (type `[]`)
- `loaded`: Event handler called when the children of a node have been loaded (lazy mode). (type `[node: CascaderNode<T>]`; parameters `node: CascaderNode<T>`)

### CascaderSearchInput

- No documented props, emits, slots, or slot props were available.

### CascaderTags

#### Slots
Slots for the CascaderTags component.
- `tag`: Custom content for a single tag in multiple mode. (type `((props: CascaderCompactTagSlotProps<T>) => any) | undefined`)
- `value`: Custom content shown when there is no selection. (type `(() => any) | undefined`)

### CascaderTrigger

#### Props
Properties for the CascaderTrigger component.
- `disabled`: When `true`, prevents the user from interacting with the trigger. (type `boolean`; optional)
- `reference`: No description. (type `ReferenceElement`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CascaderValue

#### Props
Properties for the CascaderValue component.
- `placeholder`: The content shown when no node is selected. (type `string`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI implements cascader with a self-developed data engine (`useCascaderData`) rather than reusing the listbox selection/collection bases, whose flat single-value model does not fit tree cascading: `shallowReactive` node trees cache `pathValues` / `pathLabels` / `level` for O(1) lookups, the `menus` computed derives the visible columns, and cascading checks run `setCheckedDeep` / `recomputeAncestors` / `collectCheckedNodes`. `CascaderOption` dispatches cancellable `select` / `expand` custom events (reka-ui style). The `scv()` recipe `cascaderVariants` declares 16 slots and 7 size variants.

| Capability                        | SoybeanUI | Ant Design `Cascader` | reka-ui `Cascader` | Element Plus `Cascader` |
| :-------------------------------- | :-------: | :-------------------: | :----------------: | :---------------------: |
| headless/styled split             |    ✅     |           —           |         ✅         |            —            |
| Multi-column panel                |    ✅     |          ✅           |         ✅         |           ✅            |
| Cascading checks + half-check     |    ✅     |          ✅           |         —          |           ✅            |
| Lazy loading / remote search      |    ✅     |          ✅           |         ✅         |           ✅            |
| `showCheckedStrategy`             |    ✅     |          ✅           |         —          |            —            |
| `pathMode` (path values)          |    ✅     |          ✅           |         —          |            —            |
| Virtual scrolling                 |    ✅     |           —           |         —          |            —            |
| Cancellable custom events         |    ✅     |           —           |         ✅         |            —            |
| Localized strings (not hardcoded) |    ✅     |           —           |         —          |           ✅            |
| axe-clean (open state)            |    ✅     |           —           |         —          |            —            |

### Cautions

- All built-in strings are localized (`LocaleCascaderMessages`); override per instance with `emptyLabel` / `clearLabel` or the matching `aria-label` attrs.
- In filterable mode the trigger becomes `tabindex=-1` and focus lives in the search input — keyboard navigation starts there.
- Clicking a non-leaf node in search mode only highlights it; the multi-column path does not expand (differs from AntD) — expand on demand if you need that behavior.
- `select` / `expand` events still fire on disabled items (emitted before the guard) without changing the model value; guard in the consumer if needed.

## FAQ

### How do I get the full path instead of the last value?

Enable `pathMode`; the model value then carries the complete value/label path rather than the deepest node only.

### How do I load children lazily from an API?

Pass `loadChildren` returning the children for a node; the engine tracks the loading state and emits `loaded` when it finishes.

### How do I filter remotely?

Use `searchDelay` for debouncing and provide your own `filter` implementation (or feed filtered `items`); the built-in filtering matches path labels client-side.

### How do I emit only checked leaves?

Configure `showCheckedStrategy: 'child'` to collect only leaf nodes when a parent is checked, or `'parent'` to emit the checked parents.

## Checkbox

- Page URL: /components/checkbox
- Markdown URL: /components/checkbox.md
- Description: A control that lets the user select or clear an option, with an indeterminate half-check state for partial selections. It ships as a standalone control, a roving-focus group, and data-driven card variants. Use it for independent toggles, multi-select lists, and "select all" scenarios with cascading half-check; for single-choice from a set, prefer SRadioGroup.

# Checkbox

## Overview

A control that lets the user select or clear an option, with an indeterminate half-check state for partial selections. It ships as a standalone control, a roving-focus group, and data-driven card variants. Use it for independent toggles, multi-select lists, and "select all" scenarios with cascading half-check; for single-choice from a set, prefer `SRadioGroup`.

## Usage

Usage examples for checkbox are rendered on the site.

## Features

- ☑️ Tri-state model — `CheckedState` of `boolean | 'indeterminate'`, reflected via both `aria-checked` (`mixed`) and `data-state`
- 🗂 Groups with roving-focus keyboard navigation (`useRovingFocusGroup`, Arrow keys)
- 🏷 Accessible label — `SCheckboxLabel` wires `for` to the control's `id`
- 📋 Native form proxy — renders a visually hidden input carrying `name` / `value` (default `'on'`) / `checked` for form submission
- 🃏 Card variants (`SCheckboxCard` / `SCheckboxCardGroup`) with icon, label, and description content
- 🎨 6 sizes, 8 colors, 2 shapes, and horizontal/vertical orientation via `checkboxVariants`
- 📊 Data-driven Compact aggregation — `CheckboxGroupCompact` / `CheckboxCardGroupCompact` own iteration and default composition
- ♿ `role="checkbox"` with full aria support, axe-clean across all four forms

## Component family

- `SCheckbox` - base checkbox with label, control, and indicator
- `SCheckboxGroup` - vertical/horizontal group with roving-focus navigation and form proxy
- `SCheckboxCard` - card checkbox with icon, label, and description
- `SCheckboxCardGroup` - data-driven group of card checkboxes

## Demos

Interactive demos for checkbox are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (13): Checkbox, CheckboxCard, CheckboxCardCompact, CheckboxCardGroup, CheckboxCardGroupCompact, CheckboxCompact, CheckboxControl, CheckboxGroup, CheckboxGroupCompact, CheckboxGroupRoot, CheckboxIndicator, CheckboxLabel, CheckboxRoot.

### Checkbox

#### Props
Properties for the Checkbox component.
- `class`: the class of root element (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CheckboxUi>`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `shape`: Shape of the component. (type `CheckboxShape`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `id`: Id. (type `string`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `CheckedState | null`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `CheckedState`; optional)
- `value`: The value given as data when submitted with a `name`. (type `DefinedValue`; default `on`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkbox (type `boolean`; default `false`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Checkbox component.
- `update:modelValue`: Event handler called when the value of the checkbox changes. (type `[value: CheckedState | null]`; parameters `value: CheckedState | null`)

### CheckboxCard

#### Props
Properties for the CheckboxCard component.
- `class`: the class of root element (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CheckboxCardUi>`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `shape`: Shape of the component. (type `CheckboxShape`; optional)
- `icon`: Icon rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `id`: Id. (type `string`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `CheckedState | null`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `CheckedState`; optional)
- `value`: The value given as data when submitted with a `name`. (type `DefinedValue`; default `on`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkbox (type `boolean`; default `false`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxCard component.
- `update:modelValue`: Event handler called when the value of the checkbox changes. (type `[value: CheckedState | null]`; parameters `value: CheckedState | null`)

### CheckboxCardCompact

#### Props
Properties for the CheckboxCardCompact component.
- `icon`: Icon rendered by the component. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `id`: Id. (type `string`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `CheckedState | null`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `CheckedState`; optional)
- `value`: The value given as data when submitted with a `name`. (type `DefinedValue`; default `on`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkbox (type `boolean`; default `false`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxCardCompact component.
- `update:modelValue`: Event handler called when the value of the checkbox changes. (type `[value: CheckedState | null]`; parameters `value: CheckedState | null`)

### CheckboxCardGroup

#### Props
Properties for the CheckboxCardGroup component.
- `class`: the class of group root element (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CheckboxCardUi>`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `shape`: Shape of the component. (type `CheckboxShape`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `rootProps`: Properties forwarded to the root element. (type `CheckboxRootProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T['value'][]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T['value'][]`; optional)
- `rovingFocus`: When `false`, navigating through the items using arrow keys will be disabled. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxCardGroup component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)

### CheckboxCardGroupCompact

#### Props
Properties for the CheckboxCardGroupCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `rootProps`: Properties forwarded to the root element. (type `CheckboxRootProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T['value'][]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T['value'][]`; optional)
- `rovingFocus`: When `false`, navigating through the items using arrow keys will be disabled. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxCardGroupCompact component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)

### CheckboxCompact

#### Props
Properties for the CheckboxCompact component.
- `label`: Label text rendered by the component. (type `string`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `id`: Id. (type `string`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `CheckedState | null`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `CheckedState`; optional)
- `value`: The value given as data when submitted with a `name`. (type `DefinedValue`; default `on`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkbox (type `boolean`; default `false`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxCompact component.
- `update:modelValue`: Event handler called when the value of the checkbox changes. (type `[value: CheckedState | null]`; parameters `value: CheckedState | null`)

### CheckboxControl

#### Props
Properties for the CheckboxControl component.
- `id`: Id of the element (type `string`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CheckboxGroup

#### Props
Properties for the CheckboxGroup component.
- `class`: the class of group root element (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CheckboxUi>`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `shape`: Shape of the component. (type `CheckboxShape`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `rootProps`: Properties forwarded to the root element. (type `CheckboxRootProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T['value'][]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T['value'][]`; optional)
- `rovingFocus`: When `false`, navigating through the items using arrow keys will be disabled. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxGroup component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)

### CheckboxGroupCompact

#### Props
Properties for the CheckboxGroupCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `rootProps`: Properties forwarded to the root element. (type `CheckboxRootProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `CheckboxControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `CheckboxIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `CheckboxLabelProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T['value'][]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T['value'][]`; optional)
- `rovingFocus`: When `false`, navigating through the items using arrow keys will be disabled. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxGroupCompact component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)

### CheckboxGroupRoot

#### Props
Properties for the CheckboxGroupRoot component.
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `rovingFocus`: When `false`, navigating through the items using arrow keys will be disabled. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxGroupRoot component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)

### CheckboxIndicator

#### Props
Properties for the CheckboxIndicator component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CheckboxLabel

- No documented props, emits, slots, or slot props were available.

### CheckboxRoot

#### Props
Properties for the CheckboxRoot component.
- `id`: Id. (type `string`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `CheckedState | null`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `CheckedState`; optional)
- `value`: The value given as data when submitted with a `name`. (type `DefinedValue`; default `on`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkbox (type `boolean`; default `false`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CheckboxRoot component.
- `update:modelValue`: Event handler called when the value of the checkbox changes. (type `[value: CheckedState | null]`; parameters `value: CheckedState | null`)

## Notes

### Architecture and benchmark differences

SoybeanUI builds checkbox with a single-source tri-state state machine: `CheckboxRoot` (`useControllableState` + `CheckedState`) derives `ariaChecked` (`indeterminate` → `mixed`) and `dataState` (checked / indeterminate / unchecked), which `CheckboxControl` reflects on `role="checkbox"` while `CheckboxIndicator` mounts conditionally via `usePresence`. Group value changes are emitted by `CheckboxGroupRoot`, which wraps `useRovingFocusGroup` for arrow-key navigation and renders a `VisuallyHiddenInput` form proxy. The `scv()` recipes `checkboxVariants` / `checkboxCardVariants` declare 6 sizes, 8 colors, and 2 shapes; all four Compact layers own iteration and default composition while the UI wrappers only inject variant classes.

| Capability                       | SoybeanUI | Ant Design `Checkbox` | Element Plus `Checkbox` | Mantine `Checkbox` | shadcn/ui `Checkbox` |
| :------------------------------- | :-------: | :-------------------: | :---------------------: | :----------------: | :------------------: |
| headless/styled split            |    ✅     |           —           |            —            |         —          |          ✅          |
| Tri-state (indeterminate)        |    ✅     |          ✅           |           ✅            |         ✅         |          ✅          |
| Independent `indeterminate` prop |    ➕     |          ✅           |           ✅            |         ✅         |          —           |
| Form value mapping               |    ✅     |          ✅           |           ✅            |         ✅         |          ✅          |
| Card variant (icon/description)  |    ✅     |           —           |            —            |         —          |          —           |
| Group roving-focus keyboard nav  |    ✅     |          ✅           |           ✅            |         ✅         |          —           |
| `button` variant                 |    ➕     |          ✅           |           ✅            |         —          |          —           |
| Select-all / half-check helper   |    ➕     |          ✅           |            —            |         —          |          —           |

### Cautions

- The half-check state is driven by `modelValue="indeterminate"`; a dedicated `indeterminate` prop is a roadmap enhancement, not yet implemented.
- A `disabled` group disables every item; an individual `disabled` on an item is honored inside an enabled group.
- The form proxy activates when a `name` is present — pair it with a native `<form>` or the `SForm` integration to submit values.
- The indicator uses `pointer-events: none` so clicks always land on the control itself.

## FAQ

### How do I show a partial / indeterminate state?

Pass `modelValue="indeterminate"` (or `defaultValue`); the control reflects `aria-checked="mixed"` and `data-state="indeterminate"`.

### How do I build a "select all" list?

Combine a master `SCheckbox` with `modelValue="indeterminate"` and an `SCheckboxGroup`; mirror the group's `update:modelValue` back to the master to drive the half-check.

### How do I submit checkbox values with a form?

Give the checkbox or group a `name`; the component renders a visually hidden input so native form submission carries `value` (default `'on'`) or the array of checked values.

### What is the difference between `SCheckboxCard` and `SCheckbox`?

`SCheckboxCard` renders a bordered card with `icon` / `label` / `description` content slots and a `data-[state=checked]` border highlight; `SCheckbox` is the bare control.

## Clipboard

- Page URL: /components/clipboard
- Markdown URL: /components/clipboard.md
- Description: SClipboard is a clipboard action component built on SButton that copies a plain-text value to the system clipboard with accessible button semantics and copied-state feedback.

# Clipboard

## Overview

`SClipboard` is a clipboard action component built on `SButton` that copies a plain-text value to the system clipboard with accessible button semantics and copied-state feedback.

Use it to copy short text values (install commands, invite codes, short links, IDs) or to provide a one-click copy entry next to code blocks, table rows, or cards. It is not for rich text, images, or large formatted content — the component only handles `string`.

Built on `SButton`, it inherits the same `color`/`size`/`variant`/`shape` theme tokens and `as`/`asChild` polymorphism, and is commonly paired with display components like `kbd` or `code` as a side copy entry.

## Usage

Usage examples for clipboard are rendered on the site.

## Features

- 📋 Copies a required text value on click
- 🧩 Ships with built-in icon/text content that can be overridden via `leading`/`default`/`trailing` slots
- 🌐 Defaults `copyText`/`copiedText` to localized `clipboard.copy`/`clipboard.copied` messages from `ConfigProvider`
- ✅ Exposes `ready`, `copied`, and `unsupported` states
- 🎨 Reuses `SButton`'s 8 variants, 8 colors, 6 sizes, and 4 shapes
- 🔌 Inherits `SButton`'s `as`/`asChild` polymorphism and `class` override
- 🛡️ Falls back to `execCommand('copy')` when the async Clipboard API is unavailable (disable with `legacy`)
- ♿ Keeps button semantics, disabled behavior, and `data-state` in the headless layer
- 🎯 TypeScript-safe with fully typed `ClipboardSlotProps`

## Demos

Interactive demos for clipboard are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Clipboard.

### Clipboard

#### Props
Properties for the Clipboard component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ClipboardVariant`; optional)
- `shape`: Shape of the component. (type `ClipboardShape`; optional)
- `fitContent`: Whether the component should fit its content width. (type `boolean`; optional)
- `value`: The text value to copy. (type `string`; required)
- `copiedDuration`: The duration in milliseconds to keep the copied state. (type `number`; default `2000`; optional)
- `legacy`: Whether to enable the legacy `execCommand` fallback. (type `boolean`; default `true`; optional)
- `copyIcon`: The icon to display before copying. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; default `'lucide:copy'`; optional)
- `copiedIcon`: The icon to display after copying. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; default `'lucide:check'`; optional)
- `copyText`: The text to display before copying. Defaults to the localized `clipboard.copy` message from `ConfigProvider`. (type `string`; optional)
- `copiedText`: The text to display after copying. Defaults to the localized `clipboard.copied` message from `ConfigProvider`. (type `string`; optional)
- `onlyIcon`: Whether to only render the icon without any text. (type `boolean`; default `false`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Clipboard component.
- `click`: Emitted when click occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `copied`: Emitted when copied occurs. (type `[value: string]`; parameters `value: string`)
- `copyError`: Emitted when copy error occurs. (type `[error: unknown]`; parameters `error: unknown`)
#### Slots
Slots for the Clipboard component.
- `leading`: No description. (type `((props: ClipboardSlotProps) => any) | undefined`)
- `default`: No description. (type `((props: ClipboardSlotProps) => any) | undefined`)
- `trailing`: No description. (type `((props: ClipboardSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the Clipboard component.
- `copied`: Whether copied. (type `boolean`; required)
- `disabled`: Whether the component is disabled. (type `boolean`; required)
- `icon`: Icon rendered by the component. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; required)
- `supported`: Whether supported. (type `boolean`; required)
- `state`: State exposed in the slot scope. (type `'ready' | 'copied' | 'unsupported'`; required)
- `text`: Text exposed in the slot scope. (type `string`; required)
- `copy`: Copy exposed in the slot scope. (type `() => Promise<void>`; required)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the clipboard into a headless layer (`@soybeanjs/headless/clipboard`) that owns copy state, button semantics, and slot props, and a styled layer (`@soybeanjs/ui`) that reuses the button variant recipe. This mirrors the headless/styled split used by `shadcn/ui` copy patterns and differs from single-package libraries such as Ant Design, Element Plus, MUI, Mantine, and Naive UI.

| Aspect        | SoybeanUI                                                                              | Ant Design / Element Plus / MUI / Mantine / Naive UI          |
| :------------ | :------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| Architecture  | headless + styled split on top of `Button`                                             | single-package `CopyButton` / `Typography.Paragraph copyable` |
| Styling       | UnoCSS utilities via shared `buttonVariants` recipe                                    | CSS-in-JS / SCSS / CSS vars                                   |
| Customization | `class`, `as` / `asChild`, `leading` / `default` / `trailing` slots                    | `icon`, `text`, `format`, component overrides                 |
| Fallback      | `legacy` prop enables a self-implemented `execCommand('copy')` fallback in `shared.ts` | library-specific fallback behavior                            |
| Feedback      | `data-state`, slot props, `copied` / `copyError` events                                | tooltip, message, or inline text swap                         |

### Cautions

- **Secure context**: The async Clipboard API (`navigator.clipboard.writeText`) is only available in secure contexts (HTTPS or `localhost`). In non-secure contexts the API is unavailable; the component falls back to the `legacy` `execCommand('copy')` (when `legacy=true`, the default) or enters the `unsupported` state (when `legacy=false`).
- **Legacy fallback deprecation**: `document.execCommand('copy')` is deprecated. `legacy` defaults to `true` for maximum compatibility; set `legacy={false}` to rely solely on the async API.
- **SSR / hydration**: `isClipboardWriteSupported()` returns `false` on the server (no `navigator`). With the default `legacy=true`, SSR renders `ready` and hydrates consistently. With `legacy=false`, SSR renders `unsupported` and may hydrate to `ready` on a supporting client — wrap in `<ClientOnly>` if this hydration difference matters.
- **Timer cleanup**: The `copied` state auto-resets after `copiedDuration` (default 2000ms) via `useTimeoutFn`, which is cleaned up on unmount — no manual timer management needed.

## FAQ

**How do I customize the copied-state UI?**
Use the `leading`, default, or `trailing` slots. Each slot receives `ClipboardSlotProps` with `copied`, `disabled`, `icon`, `supported`, `state`, `text`, and a `copy()` helper.

**How do I build an icon-only copy button?**
Clear the default slot and pass an explicit `aria-label` (or `copy-text` plus visible text in another slot). See the `icon-only` playground demo.

**What happens when the Clipboard API is unavailable?**
When neither the async Clipboard API nor the legacy fallback can run, the component exposes `data-state="unsupported"` and disables interaction. Set `legacy={false}` if you want to opt out of the `execCommand('copy')` fallback.

**How do I handle copy failures?**
Listen for the `copyError` event. The component keeps `data-state="ready"` on failure so users can retry without entering a false copied state.

**How do I localize the built-in copy text?**
The default `copyText`/`copiedText` resolve to the `clipboard.copy`/`clipboard.copied` messages of the locale selected by `ConfigProvider` (falling back to `en`). Pass explicit `copy-text`/`copied-text` props, or a `messages` override on `ConfigProvider`, to customize them.

**Can I copy programmatically?**
Yes. Call the `copy()` function from slot props, or trigger the button and listen for the `copied` event.

## Collapsible

- Page URL: /components/collapsible
- Markdown URL: /components/collapsible.md
- Description: An interactive component that expands/collapses a panel. SCollapsible wraps the headless CollapsibleRoot with the collapsibleVariants style recipe (3 slots: root/trigger/content; 6 sizes), and the headless CollapsibleTrigger/CollapsibleContent primitives provide the toggle button and the animated panel.

# Collapsible

## Overview

An interactive component that expands/collapses a panel. `SCollapsible` wraps the headless `CollapsibleRoot` with the `collapsibleVariants` style recipe (3 slots: root/trigger/content; 6 sizes), and the headless `CollapsibleTrigger`/`CollapsibleContent` primitives provide the toggle button and the animated panel.

Use it for a single "expand to reveal" section, FAQ items, or inline collapsible filters. Prefer `accordion` when you need multiple coordinated sections (single/multiple open), and `dialog`/`popover` for floating surfaces.

## Usage

Usage examples for collapsible are rendered on the site.

## Features

- 🧩 Headless/styled split — `SCollapsible` injects `collapsibleVariants`; the headless primitives own state, a11y and animation
- 🎛️ Controlled / uncontrolled — `v-model:open` or `defaultOpen`
- 📜 Animated panel — `CollapsibleContent` measures real dimensions and animates open/closed via `data-state`
- 🗑️ `unmountOnHide` — removes closed content from the DOM, or keeps it mounted (hidden)
- 🧲 `forceMount` — keep content present even when closed (for measurement/custom animation)
- 🔗 Accessible wiring — the trigger exposes `aria-expanded`/`aria-controls`; root/content reflect `data-state`/`data-disabled`
- 🔧 Polymorphic — `as`/`asChild` on root, trigger and content

## Component family

- `SCollapsible` (styled) — the root wrapper; `collapsibleVariants` recipe and `provideCollapsibleUi`
- `CollapsibleRoot` (headless) — the state owner; `useControllableState` + `provideCollapsibleRootContext`
- `CollapsibleTrigger` (headless) — the `Button`-based trigger; `aria-expanded`/`aria-controls`/`data-state`
- `CollapsibleContent` (headless) — the animated panel; presence-based dimension measurement and `data-state`

## Demos

Interactive demos for collapsible are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger.

### Collapsible

#### Props
Properties for the Collapsible component.
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CollapsibleUi>`; optional)
- `defaultOpen`: The open state of the collapsible when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the collapsible. Can be bound with `v-model`. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the collapsible. (type `boolean`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Collapsible component.
- `update:open`: Event handler called when the open state of the collapsible changes. (type `[value: boolean]`; parameters `value: boolean`)

### CollapsibleContent

#### Props
Properties for the CollapsibleContent component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### CollapsibleRoot

#### Props
Properties for the CollapsibleRoot component.
- `defaultOpen`: The open state of the collapsible when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the collapsible. Can be bound with `v-model`. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the collapsible. (type `boolean`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the CollapsibleRoot component.
- `update:open`: Event handler called when the open state of the collapsible changes. (type `[value: boolean]`; parameters `value: boolean`)

### CollapsibleTrigger

#### Props
Properties for the CollapsibleTrigger component.
- `disabledCollapsible`: When `true`, prevents the user from toggling the collapsible. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`SCollapsible` is a thin styled wrapper; the headless primitives own the open state (`useControllableState`), the presence/animation cycle (`usePresence` + `getBoundingClientRect` dimension measurement) and the accessibility wiring (`aria-expanded`/`aria-controls`/`data-state`). This mirrors shadcn/ui and Radix's headless `Collapsible`, unlike Ant Design, Element Plus and Mantine which ship a config-driven collapsible or fold. SoybeanUI routes the trigger through its `Button` primitive so the styled `Button` variants are reused instead of a bespoke toggle.

| Capability              | SoybeanUI | shadcn/ui | Radix Collapsible | Ant Design | Element Plus | Mantine |
| :---------------------- | :-------: | :-------: | :---------------: | :--------: | :----------: | :-----: |
| Headless/styled split   |    ✅     |    ✅     |        ✅         |     —      |      —       |    —    |
| Controlled/uncontrolled |    ✅     |    ✅     |        ✅         |     ✅     |      ✅      |   ✅    |
| Height animation        |    ✅     |    ✅     |        ✅         |     ✅     |      ✅      |   ✅    |
| `unmountOnHide`         |    ✅     |    ✅     |        ✅         |     —      |      —       |    —    |
| `forceMount`            |    ✅     |    ✅     |        ✅         |     —      |      —       |    —    |
| `as`/`asChild`          |    ✅     |    ✅     |        ✅         |     —      |      —       |    —    |
| Trigger reuses Button   |    ✅     |     —     |         —         |     —      |      —       |    —    |

`—` = unsupported or a different interaction model.

### Cautions

- The collapse animation measures real dimensions with `getBoundingClientRect`, so it only runs on the client; under SSR the first paint renders the open/closed state without animating.
- With `unmountOnHide: true` (default) closed content is removed from the DOM; with `false` it stays mounted but is hidden (`hidden="until-found"`).
- `forceMount` keeps the content element present even when closed — combine it with your own animation/transition to control reveal.
- Wire the trigger via the headless `CollapsibleTrigger` (a `Button`) so `aria-expanded`/`aria-controls` stay correct; a custom button must set these manually.
- The content element carries `data-state`/`data-disabled` and the recipe's `data-[state=open]:animate-*` classes drive the transition.

### Roadmap

No blocking gaps identified for the core collapsible API.

## FAQ

### How do I build a collapsible with a toggle?

Use `SCollapsible` with the headless `CollapsibleTrigger` for a styled button trigger:

```vue

  <template #default="{ open }">
    <SCollapsibleTrigger>Toggle ({{ open ? 'on' : 'off' }})</SCollapsibleTrigger>
    <SCollapsibleContent>Hidden panel content</SCollapsibleContent>
  </template>

```

### How do I control the open state?

Bind `open` with `v-model` (or use `default-open`):

```vue
<SCollapsible v-model:open="open">…</SCollapsible>
```

### How do I keep the content mounted when closed?

Set `unmount-on-hide="false"` so it stays in the DOM (hidden) instead of being removed:

```vue
<SCollapsible :unmount-on-hide="false">…</SCollapsible>
```

### How do I animate with my own transition?

Use `force-mount` and drive the reveal with your own classes or a `<Transition>`:

```vue
<SCollapsible force-mount>…</SCollapsible>
```

### Is the panel keyboard accessible?

Yes — the `CollapsibleTrigger` is a real `<button>` that sets `aria-expanded` and `aria-controls` to the content id, and the content reflects `data-state`; focus stays on the trigger after toggling.

## Color Area

- Page URL: /components/color-area
- Markdown URL: /components/color-area.md
- Description: A two-dimensional color editor for saturation/lightness, saturation/brightness, or OKLCH chroma/lightness selection. SColorArea combines the headless ColorAreaRoot/ColorAreaArea/ColorAreaThumb primitives with the colorAreaVariants style recipe (3 slots, 6 sizes).

# Color Area

## Overview

A two-dimensional color editor for saturation/lightness, saturation/brightness, or OKLCH chroma/lightness selection. `SColorArea` combines the headless `ColorAreaRoot`/`ColorAreaArea`/`ColorAreaThumb` primitives with the `colorAreaVariants` style recipe (3 slots, 6 sizes).

Use a color area for a saturation/lightness plane inside a color picker (typically paired with `color-slider` for the hue channel).

## Usage

Usage examples for color-area are rendered on the site.

## Features

- 🧩 Headless/styled split — `ColorAreaCompact` composes the area + thumb; `SColorArea` only injects styles and forwards props/events
- 🎛️ Axis channels — `xChannel`/`yChannel` pick `hue`/`saturation`/`lightness`/`brightness`/`chroma`
- 🎨 Color spaces — `colorSpace` (e.g. `hsl`, `oklch`) with `format` for the emitted string
- ⌨️ Keyboard — arrow keys adjust the thumb in fine/step increments; `role="application"` + `role="slider"`
- 📝 Form fields — hidden `x`/`y` inputs via `xName`/`yName` for native form submission
- 🔒 Disabled — `disabled` disables interaction
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides

## Component family

- `SColorArea` (styled) — the entry wrapper; `colorAreaVariants` recipe with dynamic slot forwarding
- `ColorAreaRoot` (headless) — the state owner; `modelValue`/`color`, axis channels, `colorSpace`/`format`, `updateValues`/`commitValues`
- `ColorAreaArea` (headless) — the 2D plane surface
- `ColorAreaThumb` (headless) — the draggable position indicator
- `ColorAreaCompact` (headless) — the aggregated composite; composes area + thumb

## Demo

Interactive demos for color-area are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): ColorArea, ColorAreaArea, ColorAreaCompact, ColorAreaRoot, ColorAreaThumb.

### ColorArea

#### Props
Properties for the ColorArea component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ColorAreaUi>`; optional)
- `areaProps`: Properties forwarded to the area element. (type `ColorAreaAreaProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `ColorAreaThumbProps`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `xChannel`: X channel. (type `ColorAreaAxisChannel`; optional)
- `yChannel`: Y channel. (type `ColorAreaAxisChannel`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `xName`: X name. (type `string`; optional)
- `yName`: Y name. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorArea component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `changeEnd`: Emitted when change end occurs. (type `[value: string]`; parameters `value: string`)

### ColorAreaArea

#### Props
Properties for the ColorAreaArea component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ColorAreaCompact

#### Props
Properties for the ColorAreaCompact component.
- `areaProps`: Properties forwarded to the area element. (type `ColorAreaAreaProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `ColorAreaThumbProps`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `xChannel`: X channel. (type `ColorAreaAxisChannel`; optional)
- `yChannel`: Y channel. (type `ColorAreaAxisChannel`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `xName`: X name. (type `string`; optional)
- `yName`: Y name. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorAreaCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `changeEnd`: Emitted when change end occurs. (type `[value: string]`; parameters `value: string`)

### ColorAreaRoot

#### Props
Properties for the ColorAreaRoot component.
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `xChannel`: X channel. (type `ColorAreaAxisChannel`; optional)
- `yChannel`: Y channel. (type `ColorAreaAxisChannel`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `xName`: X name. (type `string`; optional)
- `yName`: Y name. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorAreaRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `changeEnd`: Emitted when change end occurs. (type `[value: string]`; parameters `value: string`)

### ColorAreaThumb

#### Props
Properties for the ColorAreaThumb component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`ColorAreaCompact` owns the area/thumb composition while every primitive stays style-free and only the UI wrapper injects the `colorAreaVariants` classes. This mirrors radix-ui-color/shadcn-ui headless split. Ant Design, Element Plus, Mantine and Naive UI ship a full color-picker with an embedded saturation plane; SoybeanUI exposes the area as a standalone configurable primitive with axis-channel, color-space and format control, plus native form inputs and a `size` scale.

| Capability            | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :-------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Configurable axes     |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Multiple color spaces |    ✅     |    ✅     |     —      |      —       |   ✅    |    —     |
| Keyboard interaction  |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Native form inputs    |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Sizes (6)             |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model (most ship a single combined color-picker).

### Cautions

- `modelValue` accepts a color string or `ColorValue`; `format` controls the emitted string format.
- `xChannel`/`yChannel` must be distinct and valid for the chosen `colorSpace` (e.g. `chroma`+`lightness` in OKLCH).
- The component emits `update:modelValue`, `update:color`, `change` and `changeEnd`; `changeEnd` fires on pointer/keyboard commit.
- Provide `xName`/`yName` to submit the underlying channels as hidden form fields.
- Use with `color-slider` (hue) and a `color-field` for a complete picker.

### Roadmap

N/A — color-area is feature-complete for the current parity set.

## FAQ

### How do I use a color area?

Set `model-value`, `format` and the axis channels:

```vue

```

### How do I configure the axes?

Use `x-channel`/`y-channel`:

```vue

```

### How do I pair it with a hue slider?

Combine with `SColorSlider` for the hue channel:

```vue

```

## Color Field

- Page URL: /components/color-field
- Markdown URL: /components/color-field.md
- Description: An input for editing either a full color string or a single channel, with support for hex, rgb, hsl, and oklch output. SColorField combines the headless ColorFieldRoot/ColorFieldInput primitives with the colorFieldVariants style recipe (2 slots, 6 sizes).

# Color Field

## Overview

An input for editing either a full color string or a single channel, with support for `hex`, `rgb`, `hsl`, and `oklch` output. `SColorField` combines the headless `ColorFieldRoot`/`ColorFieldInput` primitives with the `colorFieldVariants` style recipe (2 slots, 6 sizes).

Use a color field for typed color entry or for editing a single channel numerically inside a color picker (paired with `color-area`/`color-slider`).

## Usage

Usage examples for color-field are rendered on the site.

## Features

- 🧩 Headless/styled split — `ColorFieldCompact` composes the root + input; `SColorField` only injects styles and forwards props/events
- 🎨 Formats — `hex`/`rgb`/`hsl`/`oklch` output via `format`; `colorSpace` + `channel` for single-channel editing
- ⌨️ Keyboard — ArrowUp/Down, PageUp/Down, Home/End increment/decrement the focused channel (with `step`)
- 🖱️ Wheel — scroll adjusts the channel unless `disableWheelChange`
- 🏷️ Placeholder/disabled/readonly — `placeholder`, `disabled`, `readonly`
- 📝 Form field — a hidden input via `name` for native form submission
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides

## Component family

- `SColorField` (styled) — the entry wrapper; `colorFieldVariants` recipe with dynamic slot forwarding
- `ColorFieldRoot` (headless) — the state owner; `modelValue`/`color`, `format`/`colorSpace`/`channel`, keyboard/wheel increment helpers
- `ColorFieldInput` (headless) — the text input bound to the color/channel
- `ColorFieldCompact` (headless) — the aggregated composite; composes root + input

## Demo

Interactive demos for color-field are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): ColorField, ColorFieldCompact, ColorFieldInput, ColorFieldRoot.

### ColorField

#### Props
Properties for the ColorField component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ColorFieldUi>`; optional)
- `inputProps`: Properties forwarded to the input element. (type `ColorFieldInputProps`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `channel`: Channel. (type `ColorChannel`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `placeholder`: Placeholder. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `disableWheelChange`: Whether to disable wheel change. (type `boolean`; optional)
- `step`: Step. (type `number`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorField component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)

### ColorFieldCompact

#### Props
Properties for the ColorFieldCompact component.
- `inputProps`: Properties forwarded to the input element. (type `ColorFieldInputProps`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `channel`: Channel. (type `ColorChannel`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `placeholder`: Placeholder. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `disableWheelChange`: Whether to disable wheel change. (type `boolean`; optional)
- `step`: Step. (type `number`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorFieldCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)

### ColorFieldInput

- No documented props, emits, slots, or slot props were available.

### ColorFieldRoot

#### Props
Properties for the ColorFieldRoot component.
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `channel`: Channel. (type `ColorChannel`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `placeholder`: Placeholder. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `disableWheelChange`: Whether to disable wheel change. (type `boolean`; optional)
- `step`: Step. (type `number`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorFieldRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)

## Notes

### Architecture and benchmark differences

`ColorFieldCompact` owns the root/input composition while every primitive stays style-free and only the UI wrapper injects the `colorFieldVariants` classes. This mirrors radix-ui-color/shadcn-ui headless split. Ant Design, Element Plus, Mantine and Naive UI ship a single color-picker with a hex input; SoybeanUI exposes a standalone color field with full format/channel control, keyboard/wheel editing and a native form input.

| Capability            | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :-------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Multiple formats      |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Single-channel edit   |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Keyboard + wheel      |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Native form input     |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Sizes (6)             |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- `modelValue` accepts a color string or `ColorValue`; `format` controls the emitted string format.
- To edit a single channel, set `channel` with a matching `colorSpace` (e.g. `lightness` in `hsl`); otherwise the full string is edited.
- Keyboard (Arrow/Page/Home/End) and wheel change the focused channel by `step` (default); set `disableWheelChange` to suppress wheel edits.
- Provide `name` to submit the color as a hidden form field.
- Use with `color-area`/`color-slider` inside a `color-picker` for a complete editor.

### Roadmap

N/A — color-field is feature-complete for the current parity set.

## FAQ

### How do I use a color field?

Bind `model-value` and choose a `format`:

```vue

```

### How do I edit a single channel?

Set `channel` with a matching `color-space`:

```vue

```

### How do I disable wheel editing?

Set `disable-wheel-change`:

```vue

```

## Color Picker

- Page URL: /components/color-picker
- Markdown URL: /components/color-picker.md
- Description: A composite color picker that combines a color area, hue/alpha sliders, formatted inputs, and preset swatches, with full oklch editing and output support. SColorPicker composes the headless color primitives (ColorArea/ColorSlider/ColorField/ColorSwatch/ColorSwatchPicker) inside a popover, with a SegmentCompact for format switching. Nested part styles are unified in colorPickerVariants and forwarded through provideColorPickerUi.

# Color Picker

## Overview

A composite color picker that combines a color area, hue/alpha sliders, formatted inputs, and preset swatches, with full `oklch` editing and output support. `SColorPicker` composes the headless color primitives (`ColorArea`/`ColorSlider`/`ColorField`/`ColorSwatch`/`ColorSwatchPicker`) inside a popover, with a `SegmentCompact` for format switching. Nested part styles are unified in `colorPickerVariants` and forwarded through `provideColorPickerUi`.

Use a color picker for a full-featured color selection UI (format tabs, saturation plane, hue/alpha sliders, swatch presets and formatted input).

## Usage

Usage examples for color-picker are rendered on the site.

## Features

- 🧩 Composite headless — composes `ColorArea`/`ColorSlider`/`ColorField`/`ColorSwatchPicker` inside a `Popover`, each style-free
- 🎛️ Format tabs — `SegmentCompact` switches `hex`/`rgb`/`hsl`/`oklch`; `update:format` reflects the active format
- 🎨 Full `oklch` support — `colorSpace="oklch"` with chroma/lightness area and formatted OKLCH output
- 🎚️ Hue + alpha sliders — `showAlpha` toggles the alpha channel slider and field
- 📝 Formatted field — `showFields` renders a hex/format input plus an alpha field
- 🖼️ Preset swatches — `showSwatches` + `swatches` render clickable presets (`ColorSwatchPicker`)
- 🪟 Popover trigger — `open`/`modal`/`placement`, with a trigger showing the current value
- 🔒 Disabled — `disabled` disables all controls
- 📐 6 sizes — xs–2xl `size`; per-part `ui` overrides

## Component family

- `SColorPicker` (styled) — the entry wrapper; computes `colorPickerVariants` and calls `provideColorPickerUi`
- `ColorPickerCompact` (headless) — the aggregated composite; wires root, popover, area, sliders, fields and swatches
- `ColorPickerRoot` (headless) — the shared color state (`color`/`hexValue`/`displayFormat`/`areaChannel`/`setColor`/`setFormat`)
- `ColorPickerTrigger` (headless) — the button showing the current value
- Underlying primitives — `ColorAreaCompact`, `ColorSliderCompact`, `ColorFieldCompact`, `ColorSwatchCompact`, `ColorSwatchPickerCompact`, `PopoverCompact`, `SegmentCompact`

## Demo

Interactive demos for color-picker are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): ColorPicker, ColorPickerCompact, ColorPickerRoot, ColorPickerTrigger.

### ColorPicker

#### Props
Properties for the ColorPicker component.
- `class`: Additional class names applied to the trigger element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ColorPickerUi>`; optional)
- `showAlpha`: Whether to show an alpha. (type `boolean`; optional)
- `showFields`: Whether to show a fields. (type `boolean`; optional)
- `showSwatches`: Whether to show a swatches. (type `boolean`; optional)
- `swatches`: Swatches. (type `string[]`; optional)
- `swatchProps`: Properties forwarded to the swatch element. (type `ColorSwatchCompactProps`; optional)
- `segmentProps`: Properties forwarded to the segment element. (type `SegmentCompactProps<ColorPickerFormatOptionData>`; optional)
- `areaProps`: Properties forwarded to the area element. (type `ColorAreaCompactProps`; optional)
- `hueSliderProps`: Properties forwarded to the hue slider element. (type `ColorSliderCompactProps`; optional)
- `alphaSliderProps`: Properties forwarded to the alpha slider element. (type `ColorSliderCompactProps`; optional)
- `alphaFieldProps`: Properties forwarded to the alpha field element. (type `ColorFieldCompactProps`; optional)
- `fieldProps`: Properties forwarded to the field element. (type `ColorFieldCompactProps`; optional)
- `swatchPickerProps`: Properties forwarded to the swatch picker element. (type `ColorSwatchPickerCompactProps<false>`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `defaultFormat`: Default format. (type `ColorFormat`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopperPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
#### Emits
Events for the ColorPicker component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `update:format`: Emitted when the format value changes. (type `[value: ColorFormat]`; parameters `value: ColorFormat`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)

### ColorPickerCompact

#### Props
Properties for the ColorPickerCompact component.
- `showAlpha`: Whether to show an alpha. (type `boolean`; optional)
- `showFields`: Whether to show a fields. (type `boolean`; optional)
- `showSwatches`: Whether to show a swatches. (type `boolean`; optional)
- `swatches`: Swatches. (type `string[]`; optional)
- `swatchProps`: Properties forwarded to the swatch element. (type `ColorSwatchCompactProps`; optional)
- `segmentProps`: Properties forwarded to the segment element. (type `SegmentCompactProps<ColorPickerFormatOptionData>`; optional)
- `areaProps`: Properties forwarded to the area element. (type `ColorAreaCompactProps`; optional)
- `hueSliderProps`: Properties forwarded to the hue slider element. (type `ColorSliderCompactProps`; optional)
- `alphaSliderProps`: Properties forwarded to the alpha slider element. (type `ColorSliderCompactProps`; optional)
- `alphaFieldProps`: Properties forwarded to the alpha field element. (type `ColorFieldCompactProps`; optional)
- `fieldProps`: Properties forwarded to the field element. (type `ColorFieldCompactProps`; optional)
- `swatchPickerProps`: Properties forwarded to the swatch picker element. (type `ColorSwatchPickerCompactProps<false>`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `defaultFormat`: Default format. (type `ColorFormat`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopperPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
#### Emits
Events for the ColorPickerCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `update:format`: Emitted when the format value changes. (type `[value: ColorFormat]`; parameters `value: ColorFormat`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)

### ColorPickerRoot

#### Props
Properties for the ColorPickerRoot component.
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `format`: Format. (type `ColorFormat`; optional)
- `defaultFormat`: Default format. (type `ColorFormat`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the ColorPickerRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `update:format`: Emitted when the format value changes. (type `[value: ColorFormat]`; parameters `value: ColorFormat`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
#### Slot Props
Slot properties for the ColorPickerRoot component.
- `color`: Theme color of the component. (type `ComputedRef<import("@soybeanjs/colord").AnyColor>`; required)
- `formattedValue`: Formatted value exposed in the slot scope. (type `ComputedRef<string>`; required)
- `hexValue`: Hex value exposed in the slot scope. (type `ComputedRef<string>`; required)
- `displayFormat`: Display format exposed in the slot scope. (type `ComputedRef<ColorFormat>`; required)
- `displayFormatLabel`: Display format label exposed in the slot scope. (type `ComputedRef<string>`; required)
- `areaXChannel`: X channel exposed in the slot scope. (type `ComputedRef<'saturation' | 'chroma'>`; required)
- `areaYChannel`: Y channel exposed in the slot scope. (type `ComputedRef<'lightness' | 'brightness'>`; required)
- `setColor`: Set color exposed in the slot scope. (type `(color: ColorValue) => void`; required)
- `setFormat`: Set format exposed in the slot scope. (type `(format: ColorFormat) => void`; required)

### ColorPickerTrigger

#### Props
Properties for the ColorPickerTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`ColorPickerCompact` owns the cross-primitive composition (root state + popover + area + sliders + fields + swatches + segment) while every underlying primitive stays style-free. The UI wrapper injects a single `colorPickerVariants` map through `provideColorPickerUi`, which remaps aliased slots onto the nested `provide*Ui` contexts. This mirrors radix-ui-color/shadcn-ui's headless split. Ant Design, Element Plus, Mantine and Naive UI ship a single styled color-picker with `showAlpha`/`presets` props; SoybeanUI exposes a composite with explicit format tabs, full `oklch` editing and a `size` scale.

| Capability           | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Composite primitives |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Format tabs          |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Full oklch editing   |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Hue + alpha sliders  |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Preset swatches      |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Sizes (6)            |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- `colorSpace` (default `hsl`) drives the area channels and output; `defaultFormat`/`format` select the initial/controlled format tab.
- `showAlpha` (default `true`) adds the alpha slider and alpha field; `showFields`/`showSwatches` toggle the input/preset sections.
- `swatches` is an array of preset colors; selecting one emits `update:modelValue` and `change`.
- The picker opens in a `Popover`; bind `open` with `v-model:open` for controlled usage.
- This is the highest-level color component; prefer the individual `color-area`/`color-slider`/`color-field` for embedded, lighter-weight editors.

### Roadmap

N/A — color-picker is feature-complete for the current parity set.

## FAQ

### How do I use a color picker?

Bind `model-value` and optionally `swatches`:

```vue

```

### How do I enable OKLCH editing?

Set `color-space` and `default-format`:

```vue

```

### How do I toggle sections?

Use `show-alpha`/`show-fields`/`show-swatches`:

```vue

```

### How do I control the popover?

Bind `open` with `v-model:open`:

```vue

```

## Color Slider

- Page URL: /components/color-slider
- Markdown URL: /components/color-slider.md
- Description: A single-channel color slider for hue, alpha, and individual RGB/HSL/HSV/OKLCH channels. SColorSlider combines the headless ColorSliderRoot/ColorSliderTrack/ColorSliderThumb primitives with the shared sliderVariants style recipe (via sliderVariants).

# Color Slider

## Overview

A single-channel color slider for hue, alpha, and individual RGB/HSL/HSV/OKLCH channels. `SColorSlider` combines the headless `ColorSliderRoot`/`ColorSliderTrack`/`ColorSliderThumb` primitives with the shared `sliderVariants` style recipe (via `sliderVariants`).

Use a color slider for a single color channel — typically the hue or alpha channel inside a color picker (paired with `color-area`).

## Usage

Usage examples for color-slider are rendered on the site.

## Features

- 🧩 Headless/styled split — `ColorSliderCompact` composes track + thumb; `SColorSlider` only injects styles and forwards props/events
- 🎚️ Single channel — `channel` picks `hue`/`alpha`/`saturation`/`lightness`/`red`/`green`/`blue`/… across color spaces
- 🎨 Color spaces — `colorSpace` (e.g. `hsl`, `rgb`) with `format` for the emitted string
- ⌨️ Keyboard — ArrowLeft/Right, PageUp/Down, Home/End adjust the channel; `role="slider"`
- ↔️ Orientation — horizontal/vertical via the shared slider primitives
- 📝 Form field — a hidden input via `name` for native form submission
- 🔒 Disabled — `disabled` disables interaction
- 📐 6 sizes + colors — xs–2xl `size`, `color` accent; per-slot `ui` overrides

## Component family

- `SColorSlider` (styled) — the entry wrapper; `sliderVariants` recipe with dynamic slot forwarding
- `ColorSliderRoot` (headless) — the state owner; `modelValue`/`color`, `channel`/`colorSpace`/`format`, value + commit
- `ColorSliderTrack` (headless) — the channel gradient track
- `ColorSliderThumb` (headless) — the draggable position indicator
- `ColorSliderCompact` (headless) — the aggregated composite; composes track + thumb

## Demo

Interactive demos for color-slider are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): ColorSlider, ColorSliderCompact, ColorSliderRoot, ColorSliderThumb, ColorSliderTrack.

### ColorSlider

#### Props
Properties for the ColorSlider component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ColorSliderUi>`; optional)
- `trackProps`: Properties forwarded to the track element. (type `ColorSliderTrackProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `ColorSliderThumbProps`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `channel`: Channel. (type `'alpha' | 'hue' | 'saturation' | 'lightness' | 'brightness' | 'red' | 'green' | 'blue' | 'chroma'`; required)
- `format`: Format. (type `ColorFormat`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `inverted`: Whether inverted. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `step`: Step. (type `number`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorSlider component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `changeEnd`: Emitted when change end occurs. (type `[value: string]`; parameters `value: string`)

### ColorSliderCompact

#### Props
Properties for the ColorSliderCompact component.
- `trackProps`: Properties forwarded to the track element. (type `ColorSliderTrackProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `ColorSliderThumbProps`; optional)
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `channel`: Channel. (type `'alpha' | 'hue' | 'saturation' | 'lightness' | 'brightness' | 'red' | 'green' | 'blue' | 'chroma'`; required)
- `format`: Format. (type `ColorFormat`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `inverted`: Whether inverted. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `step`: Step. (type `number`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorSliderCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `changeEnd`: Emitted when change end occurs. (type `[value: string]`; parameters `value: string`)

### ColorSliderRoot

#### Props
Properties for the ColorSliderRoot component.
- `modelValue`: Current model value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `defaultValue`: Default value. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `colorSpace`: Color space. (type `ColorSpace`; optional)
- `channel`: Channel. (type `'alpha' | 'hue' | 'saturation' | 'lightness' | 'brightness' | 'red' | 'green' | 'blue' | 'chroma'`; required)
- `format`: Format. (type `ColorFormat`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `inverted`: Whether inverted. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `step`: Step. (type `number`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorSliderRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:color`: Emitted when the color value changes. (type `[value: NormalizedColor]`; parameters `value: NormalizedColor`)
- `change`: Emitted when change occurs. (type `[value: string]`; parameters `value: string`)
- `changeEnd`: Emitted when change end occurs. (type `[value: string]`; parameters `value: string`)

### ColorSliderThumb

#### Props
Properties for the ColorSliderThumb component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ColorSliderTrack

#### Props
Properties for the ColorSliderTrack component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`ColorSliderCompact` owns the track/thumb composition while every primitive stays style-free and only the UI wrapper injects the shared `sliderVariants` classes. This mirrors radix-ui-color/shadcn-ui headless split. Ant Design, Element Plus, Mantine and Naive UI embed the hue/alpha slider inside the color-picker; SoybeanUI exposes a standalone single-channel slider with color-space/channel control, keyboard interaction, native form input and a `size` scale.

| Capability               | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :----------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split    |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Any channel (hue/alpha…) |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Multiple color spaces    |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Keyboard interaction     |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Native form input        |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Sizes (6)                |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- `modelValue` accepts a color string or `ColorValue`; `channel` selects which channel the slider edits, and `format` controls the emitted string.
- `channel` must be valid for the chosen `colorSpace` (e.g. `hue`/`alpha` in `hsl`).
- The component emits `update:modelValue`, `update:color`, `change` and `changeEnd`; `changeEnd` fires on pointer/keyboard commit.
- Provide `name` to submit the channel as a hidden form field.
- Use with `color-area` (saturation plane) inside a `color-picker` for a complete editor.

### Roadmap

N/A — color-slider is feature-complete for the current parity set.

## FAQ

### How do I use a color slider?

Bind `model-value`, choose a `channel` and `format`:

```vue

```

### How do I edit alpha?

Set `channel="alpha"`:

```vue

```

### How do I pair it with a color area?

Combine with `SColorArea` for the saturation plane:

```vue

```

## Color Swatch

- Page URL: /components/color-swatch
- Markdown URL: /components/color-swatch.md
- Description: A read-only color preview block with support for transparent and OKLCH values. SColorSwatch combines the headless ColorSwatchRoot/ColorSwatchChecker/ColorSwatchFill primitives with the colorSwatchVariants style recipe (3 slots, 6 sizes × 2 shapes).

# Color Swatch

## Overview

A read-only color preview block with support for transparent and OKLCH values. `SColorSwatch` combines the headless `ColorSwatchRoot`/`ColorSwatchChecker`/`ColorSwatchFill` primitives with the `colorSwatchVariants` style recipe (3 slots, 6 sizes × 2 shapes).

Use a color swatch to display a color value (with an optional transparency checker) inside pickers, tables, or labels.

## Usage

Usage examples for color-swatch are rendered on the site.

## Features

- 🧩 Headless/styled split — `ColorSwatchCompact` composes checker + fill; `SColorSwatch` only injects styles and forwards props/slots
- 🖼️ Transparency checker — renders a checkerboard behind translucent/alpha colors
- 🎨 OKLCH + transparent support — accepts any `ColorValue`, including `oklch` and alpha colors
- 🏷️ Accessible label — `role="img"` with `aria-label` from `label`; empty colors marked `data-no-color`
- 🔵 Shape — `shape="square"` (default) or `"circle"`
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- 🔌 Slot scope — the default slot exposes `{ color, alpha }` (RGB string + 0–1 alpha)

## Component family

- `SColorSwatch` (styled) — the entry wrapper; `colorSwatchVariants` recipe with dynamic slot forwarding
- `ColorSwatchRoot` (headless) — the accessible preview root (`role="img"`, `color`/`label`)
- `ColorSwatchChecker` (headless) — the transparency checkerboard
- `ColorSwatchFill` (headless) — the solid color fill
- `ColorSwatchCompact` (headless) — the aggregated composite; composes checker + fill

## Demo

Interactive demos for color-swatch are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): ColorSwatch, ColorSwatchChecker, ColorSwatchCompact, ColorSwatchFill, ColorSwatchRoot.

### ColorSwatch

#### Props
Properties for the ColorSwatch component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ColorSwatchUi>`; optional)
- `shape`: Shape of the component. (type `ColorSwatchShape`; optional)
- `checkerProps`: Props for the checker element of the ColorSwatch component. (type `ColorSwatchCheckerProps`; optional)
- `fillProps`: Props for the fill element of the ColorSwatch component. (type `ColorSwatchFillProps`; optional)
- `color`: Theme color of the component. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the ColorSwatch component.
- `default`: No description. (type `((props: ColorSwatchSlotProps) => any) | undefined`)
#### Slot Props
Properties for the ColorSwatch component slots.
- `color`: Color value in RGB format, e.g., "rgb(255, 0, 0)". (type `string`; required)
- `alpha`: Alpha value of the color, ranging from 0 to 1. (type `number`; required)

### ColorSwatchChecker

- No documented props, emits, slots, or slot props were available.

### ColorSwatchCompact

#### Props
Properties for the ColorSwatch component in compact mode.
- `checkerProps`: Props for the checker element of the ColorSwatch component. (type `ColorSwatchCheckerProps`; optional)
- `fillProps`: Props for the fill element of the ColorSwatch component. (type `ColorSwatchFillProps`; optional)
- `color`: Theme color of the component. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the ColorSwatch component in compact mode.
- `default`: No description. (type `((props: ColorSwatchSlotProps) => any) | undefined`)

### ColorSwatchFill

- No documented props, emits, slots, or slot props were available.

### ColorSwatchRoot

#### Props
Properties for the ColorSwatch component.
- `color`: Theme color of the component. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the ColorSwatch component.
- `default`: No description. (type `((props: ColorSwatchSlotProps) => any) | undefined`)

## Notes

### Architecture and benchmark differences

`ColorSwatchCompact` owns the checker/fill composition while every primitive stays style-free and only the UI wrapper injects the `colorSwatchVariants` classes. This mirrors radix-ui-color/shadcn-ui headless split. Ant Design, Element Plus, Mantine and Naive UI render a plain colored `<span>` for swatches; SoybeanUI exposes an accessible `role="img"` preview with a transparency checker, shape/size control and a slot scope exposing the parsed color/alpha.

| Capability            | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :-------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Transparency checker  |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| OKLCH / alpha support |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Accessible role/img   |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Shape (square/circle) |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Sizes (6)             |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- Provide `label` for an accessible name; empty colors are marked `data-no-color` (rendered muted).
- `color` accepts a color string or `ColorValue` (including `oklch`/alpha); the fill uses the resolved CSS color.
- The default slot receives `{ color, alpha }` (RGB string + 0–1 alpha) for custom overlays/labels.
- `shape` switches between square (`rounded-md`) and circle (`rounded-full`).
- This is a read-only preview; use `color-picker`/`color-swatch-picker` for selection.

### Roadmap

N/A — color-swatch is feature-complete for the current parity set.

## FAQ

### How do I show a color swatch?

Pass `color` and an optional `label`:

```vue

```

### How do I make it circular?

Set `shape="circle"`:

```vue

```

### How do I access the parsed color/alpha?

Use the default slot scope:

```vue

  <template #default="{ alpha }">{{ (alpha * 100).toFixed(0) }}%</template>

```

## Color Swatch Picker

- Page URL: /components/color-swatch-picker
- Markdown URL: /components/color-swatch-picker.md
- Description: Choose a color quickly from a preset palette, useful for theme panels and suggested color selections. SColorSwatchPicker combines the headless ColorSwatchPickerRoot/Item/ItemSwatch/ItemIndicator primitives (built on the listbox) with the colorSwatchPickerVariants style recipe (6 slots, 6 sizes × 2 shapes).

# Color Swatch Picker

## Overview

Choose a color quickly from a preset palette, useful for theme panels and suggested color selections. `SColorSwatchPicker` combines the headless `ColorSwatchPickerRoot`/`Item`/`ItemSwatch`/`ItemIndicator` primitives (built on the listbox) with the `colorSwatchPickerVariants` style recipe (6 slots, 6 sizes × 2 shapes).

Use a swatch picker for a compact, clickable preset palette (theme panels, brand colors, suggested colors).

## Usage

Usage examples for color-swatch-picker are rendered on the site.

## Features

- 🧩 Headless/listbox based — built on the listbox primitives with `role="listbox"`/`option`, roving focus and selection
- 🎨 Preset palette — pass `colors` as an array; each renders a `ColorSwatch` with a check indicator
- 🔘 Single/multiple — `multiple` (via the listbox `M` generic) selects one or many values
- ✅ Indicator — an `indicator` slot (default `lucide:check`) marks the active swatch
- 🔵 Shape — `shape="square"` (default) or `"circle"`
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- 🧩 Custom content — the `default` slot (when no `colors`) and `swatch`/`indicator` slots for full control

## Component family

- `SColorSwatchPicker` (styled) — the entry wrapper; `colorSwatchPickerVariants` recipe with dynamic slot forwarding
- `ColorSwatchPickerCompact` (headless) — the aggregated composite; iterates `colors` into items with swatch + indicator
- `ColorSwatchPickerRoot` (headless) — the listbox root (`modelValue`, `multiple`)
- `ColorSwatchPickerItem` (headless) — a selectable swatch option (`role="option"`)
- `ColorSwatchPickerItemSwatch` (headless) — the swatch (`ColorSwatchCompact` base)
- `ColorSwatchPickerItemIndicator` (headless) — the selection check indicator

## Demo

Interactive demos for color-swatch-picker are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): ColorSwatchPicker, ColorSwatchPickerCompact, ColorSwatchPickerCompactColor, ColorSwatchPickerItem, ColorSwatchPickerItemIndicator, ColorSwatchPickerItemSwatch, ColorSwatchPickerRoot.

### ColorSwatchPicker

#### Props
Properties for the ColorSwatchPicker component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ColorSwatchPickerExtendedUi>`; optional)
- `shape`: Shape of the component. (type `ColorSwatchPickerShape`; optional)
- `colors`: Colors. (type `string[]`; optional)
- `itemProps`: Properties forwarded to the item element. (type `Omit<ColorSwatchPickerItemProps, 'value'>`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ColorSwatchPickerItemIndicatorProps`; optional)
- `swatchProps`: Properties forwarded to the swatch element. (type `ColorSwatchPickerItemSwatchProps`; optional)
- `orientation`: The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `string | string[]`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `string | string[]`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `boolean`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the ColorSwatchPicker component.
- `update:modelValue`: No description. (type `[value: string | string[]]`; parameters `value: string | string[]`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `entryFocus`: Event handler called when container is being focused. Can be prevented. (type `[event: CustomEvent<any>]`; parameters `event: CustomEvent<any>`)
- `leave`: Event handler called when the mouse leave the container (type `[event: Event]`; parameters `event: Event`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)

### ColorSwatchPickerCompact

#### Props
Properties for the ColorSwatchPickerCompact component.
- `colors`: Colors. (type `string[]`; optional)
- `itemProps`: Properties forwarded to the item element. (type `Omit<ColorSwatchPickerItemProps, 'value'>`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ColorSwatchPickerItemIndicatorProps`; optional)
- `swatchProps`: Properties forwarded to the swatch element. (type `ColorSwatchPickerItemSwatchProps`; optional)
- `orientation`: The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the ColorSwatchPickerCompact component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `entryFocus`: Event handler called when container is being focused. Can be prevented. (type `[event: CustomEvent<any>]`; parameters `event: CustomEvent<any>`)
- `leave`: Event handler called when the mouse leave the container (type `[event: Event]`; parameters `event: Event`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)
#### Slots
Slots for the ColorSwatchPickerCompact component.
- `default`: Custom content rendered when colors are not provided. (type `((props: ColorSwatchPickerCompactSlotProps<M>) => any) | undefined`)
- `swatch`: Custom content rendered inside each swatch. (type `((props: ColorSwatchPickerCompactColorSlotProps) => any) | undefined`)
- `indicator`: Custom content rendered inside each indicator. (type `((props: ColorSwatchPickerCompactColorSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the ColorSwatchPickerCompact component.
- `modelValue`: Current model value. (type `M extends true ? string[] : string`; required)

### ColorSwatchPickerCompactColor

#### Slot Props
Slot properties for color-specific ColorSwatchPickerCompact slots.
- `color`: Current swatch color. (type `string`; required)

### ColorSwatchPickerItem

#### Props
Properties for the ColorSwatchPickerItem component.
- `value`: The value given as data when submitted with a `name`. (type `string`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ColorSwatchPickerItem component.
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)

### ColorSwatchPickerItemIndicator

#### Props
Properties for the ColorSwatchPickerItemIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ColorSwatchPickerItemSwatch

#### Props
Properties for the ColorSwatchPickerItemSwatch component.
- `checkerProps`: Props for the checker element of the ColorSwatch component. (type `ColorSwatchCheckerProps`; optional)
- `fillProps`: Props for the fill element of the ColorSwatch component. (type `ColorSwatchFillProps`; optional)
- `color`: Theme color of the component. (type `import("@soybeanjs/colord").AnyColor`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ColorSwatchPickerRoot

#### Props
Properties for the ColorSwatchPickerRoot component.
- `orientation`: The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the ColorSwatchPickerRoot component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `entryFocus`: Event handler called when container is being focused. Can be prevented. (type `[event: CustomEvent<any>]`; parameters `event: CustomEvent<any>`)
- `leave`: Event handler called when the mouse leave the container (type `[event: Event]`; parameters `event: Event`)

## Notes

### Architecture and benchmark differences

`ColorSwatchPickerCompact` owns the palette iteration (item + swatch + indicator) while every primitive stays style-free and only the UI wrapper injects the `colorSwatchPickerVariants` classes. This mirrors radix-ui-color/shadcn-ui headless split, built on the shared listbox primitives. Ant Design, Element Plus, Mantine and Naive UI ship a single color-picker with a preset row; SoybeanUI exposes a standalone listbox-based swatch picker with single/multiple selection, a check indicator, shape/size control and full slot overrides.

| Capability             | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :--------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/listbox based |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Single/multiple        |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Check indicator        |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Roving focus           |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Shape (square/circle)  |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Sizes (6)              |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- `colors` is an array of color strings; each renders an `ColorSwatch` option with a check indicator on the active value.
- Selection emits `update:modelValue` (single: a string; `multiple`: an array) and `select`.
- Provide `indicator`/`swatch` slots to customize the check mark and swatch content; use the `default` slot to render fully custom content when `colors` is empty.
- `shape` switches between square (`rounded-md`) and circle (`rounded-full`).
- Built on the listbox primitives, so keyboard/roving-focus behavior follows the listbox contract.

### Roadmap

N/A — color-swatch-picker is feature-complete for the current parity set.

## FAQ

### How do I build a swatch picker?

Pass `colors` and bind `model-value`:

```vue

```

### How do I allow multiple selection?

Use `multiple` (the value becomes an array):

```vue

```

### How do I make the swatches circular?

Set `shape="circle"`:

```vue

```

### How do I customize the indicator?

Use the `indicator` slot:

```vue

  <template #indicator>✓</template>

```

## Combobox

- Page URL: /components/combobox
- Markdown URL: /components/combobox.md
- Description: A combobox for searching and selecting values from an option list, with an explicit anchor composition, clearable input, and complete popup/filtering behavior. The input filters options as you type and keyboard navigation follows the WAI-ARIA combobox pattern. Use it when users must type to filter a list; for selection without typing, use SSelect; for fuzzy-matching suggestions over text, use SAutocomplete.

# Combobox

## Overview

A combobox for searching and selecting values from an option list, with an explicit anchor composition, clearable input, and complete popup/filtering behavior. The input filters options as you type and keyboard navigation follows the WAI-ARIA combobox pattern. Use it when users must type to filter a list; for selection without typing, use `SSelect`; for fuzzy-matching suggestions over text, use `SAutocomplete`.

## Usage

Usage examples for combobox are rendered on the site.

## Features

- 🔍 Type-to-filter with a three-state filter model (matched / empty / unset)
- ⌨️ Full keyboard navigation — Arrow keys, Enter/Space select, typeahead, Escape close
- 📜 Optional virtual scrolling (`ComboboxVirtualizer`)
- 🗂 Grouping with group labels and separators
- 🧹 Trigger clear icon deselects (`clearable`); the popup cancel clears only the search input
- 🧩 `ComboboxValue` primitive renders the selected labels (or placeholder) for custom trigger layouts
- 📊 Data-driven `ComboboxCompact` API — `items` (options use `label` / `value` fields) + grouping
- 🎛 Controlled / uncontrolled with `v-model:open` and filter semantics (`ignoreFilter`, `resetSearchTermOnBlur`)
- ♿ Full accessibility support — `role="combobox"` / `listbox` / `option`, `aria-activedescendant`, axe-clean

## Demos

Interactive demos for combobox are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (20): Combobox, ComboboxAnchor, ComboboxArrow, ComboboxCancel, ComboboxClear, ComboboxCompact, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxPortal, ComboboxRoot, ComboboxSeparator, ComboboxTrigger, ComboboxValue, ComboboxViewport, ComboboxVirtualizer.

### Combobox

#### Props
Properties for the Combobox component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ComboboxUi>`; optional)
- `items`: Items rendered by the component. (type `ComboboxOptionData[]`; required)
- `placeholder`: Placeholder. (type `string`; optional)
- `searchPlaceholder`: Search placeholder. (type `string`; optional)
- `clearLabel`: Clear label. (type `string`; optional)
- `emptyLabel`: Empty label. (type `string`; optional)
- `anchorProps`: Properties forwarded to the anchor element. (type `ComboboxAnchorProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ComboboxTriggerProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `ComboboxCancelProps`; optional)
- `valueProps`: Properties forwarded to the value element. (type `ComboboxValueProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ComboboxPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ComboboxContentProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `ComboboxViewportProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `ComboboxInputProps`; optional)
- `emptyProps`: Properties forwarded to the empty element. (type `ComboboxEmptyProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `ComboboxGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ComboboxGroupLabelProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `ComboboxItemProps`; optional)
- `itemIndicatorProps`: Properties forwarded to the item indicator element. (type `ComboboxItemIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ComboboxSeparatorProps`; optional)
- `open`: The controlled open state of the Combobox. Can be bound with `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state. (type `boolean`; optional)
- `resetSearchTermOnBlur`: Whether to reset the searchTerm when the Combobox input blurred (type `boolean`; default ``true``; optional)
- `resetSearchTermOnSelect`: Whether to reset the searchTerm when the Combobox value is selected (type `boolean`; default ``true``; optional)
- `openOnFocus`: Whether to open the combobox when the input is focused (type `boolean`; default ``false``; optional)
- `openOnClick`: Whether to open the combobox when the input is clicked (type `boolean`; default ``false``; optional)
- `ignoreFilter`: When `true`, disable the default filters (type `boolean`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Combobox component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `update:open`: Emitted when the open state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: Event handler called when the positioner is placed (type `[]`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)
#### Slots
Slots for the Combobox component.
- `trigger-leading`: Custom content for the trigger leading slot. (type `(() => any) | undefined`)
- `trigger-value`: Custom content for the trigger value slot. (type `((props: ComboboxCompactTriggerValueSlotProps<M>) => any) | undefined`)
- `trigger-trailing`: Custom content for the trigger trailing slot. (type `(() => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `(() => any) | undefined`)
- `input-leading`: Custom content for the input leading slot. (type `((props: ComboboxCompactInputSlotProps) => any) | undefined`)
- `input-trailing`: Custom content for the input trailing slot. (type `((props: ComboboxCompactInputSlotProps) => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: ComboboxCompactGroupLabelSlotProps) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)
- `item-text`: Custom content for the item text slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)
- `item-indicator`: Custom content for the item indicator slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)

### ComboboxAnchor

#### Props
Properties for the ComboboxAnchor component.
- `reference`: No description. (type `ReferenceElement`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxArrow

- No documented props, emits, slots, or slot props were available.

### ComboboxCancel

#### Props
Properties for the ComboboxCancel component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxClear

#### Props
Properties for the ComboboxClear component.
- `ariaLabel`: Aria label for the clear button. (type `string`; optional)
- `disabled`: Whether the clear button is disabled. (type `boolean`; optional)

### ComboboxCompact

#### Props
Properties for the ComboboxCompact component.
- `items`: Items rendered by the component. (type `ComboboxOptionData[]`; required)
- `placeholder`: Placeholder. (type `string`; optional)
- `searchPlaceholder`: Search placeholder. (type `string`; optional)
- `clearLabel`: Clear label. (type `string`; optional)
- `emptyLabel`: Empty label. (type `string`; optional)
- `anchorProps`: Properties forwarded to the anchor element. (type `ComboboxAnchorProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ComboboxTriggerProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `ComboboxCancelProps`; optional)
- `valueProps`: Properties forwarded to the value element. (type `ComboboxValueProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ComboboxPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ComboboxContentProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `ComboboxViewportProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `ComboboxInputProps`; optional)
- `emptyProps`: Properties forwarded to the empty element. (type `ComboboxEmptyProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `ComboboxGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ComboboxGroupLabelProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `ComboboxItemProps`; optional)
- `itemIndicatorProps`: Properties forwarded to the item indicator element. (type `ComboboxItemIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ComboboxSeparatorProps`; optional)
- `open`: The controlled open state of the Combobox. Can be bound with `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state. (type `boolean`; optional)
- `resetSearchTermOnBlur`: Whether to reset the searchTerm when the Combobox input blurred (type `boolean`; default ``true``; optional)
- `resetSearchTermOnSelect`: Whether to reset the searchTerm when the Combobox value is selected (type `boolean`; default ``true``; optional)
- `openOnFocus`: Whether to open the combobox when the input is focused (type `boolean`; default ``false``; optional)
- `openOnClick`: Whether to open the combobox when the input is clicked (type `boolean`; default ``false``; optional)
- `ignoreFilter`: When `true`, disable the default filters (type `boolean`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the ComboboxCompact component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `update:open`: Emitted when the open state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: Event handler called when the positioner is placed (type `[]`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)
#### Slots
Slots for the ComboboxCompact component.
- `trigger-leading`: Custom content for the trigger leading slot. (type `(() => any) | undefined`)
- `trigger-value`: Custom content for the trigger value slot. (type `((props: ComboboxCompactTriggerValueSlotProps<M>) => any) | undefined`)
- `trigger-trailing`: Custom content for the trigger trailing slot. (type `(() => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `(() => any) | undefined`)
- `input-leading`: Custom content for the input leading slot. (type `((props: ComboboxCompactInputSlotProps) => any) | undefined`)
- `input-trailing`: Custom content for the input trailing slot. (type `((props: ComboboxCompactInputSlotProps) => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: ComboboxCompactGroupLabelSlotProps) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)
- `item-text`: Custom content for the item text slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)
- `item-indicator`: Custom content for the item indicator slot. (type `((props: ComboboxCompactItemSlotProps) => any) | undefined`)

### ComboboxContent

#### Props
Properties for the ComboboxContent component.
- `position`: Position. (type `'inline' | 'popper'`; optional)
- `bodyLock`: Whether body lock. (type `boolean`; optional)
- `hideWhenEmpty`: Whether hide when empty. (type `boolean`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopperPositioningPopupProps`; optional)
- `open`: Whether the floating layer is open. Drives the positioning lifecycle (`isPositioned` resets when open flips); the positioning primitive itself has no open state, so consumers wire their own open state here. (type `boolean`; default `true`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the anchor to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the anchor. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the anchor. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `false`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the anchor is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the anchor becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: When `true`, focus cannot escape the content via keyboard, pointer, or a programmatic focus. (type `boolean`; default `false`; optional)
- `disableOutsidePointerEvents`: When `true`, hover/focus/click interactions will be disabled on elements outside the `DismissableLayer`. Users will need to click twice on outside elements to interact with them: once to close the `DismissableLayer`, and again to trigger the element. (type `boolean`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the ComboboxContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: Event handler called when the positioner is placed (type `[]`)

### ComboboxEmpty

#### Props
Properties for the ComboboxEmpty component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxGroup

- No documented props, emits, slots, or slot props were available.

### ComboboxGroupLabel

- No documented props, emits, slots, or slot props were available.

### ComboboxInput

#### Props
Properties for the ComboboxInput component.
- `displayValue`: Display value. (type `((value: MaybeArray<string>) => string)`; optional)
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `controlProps`: The props of the input extra props. (type `InputControlProps`; optional)
- `defaultValue`: The default value of the input (type `string`; optional)
- `modelValue`: The controlled value of the input (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the ComboboxInput component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)

### ComboboxItem

#### Props
Properties for the ComboboxItem component.
- `textValue`: Text value. (type `string`; optional)
- `value`: The value given as data when submitted with a `name`. (type `string`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ComboboxItem component.
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)

### ComboboxItemIndicator

#### Props
Properties for the ComboboxItemIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxPortal

- No documented props, emits, slots, or slot props were available.

### ComboboxRoot

#### Props
Properties for the ComboboxRoot component.
- `open`: The controlled open state of the Combobox. Can be bound with `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state. (type `boolean`; optional)
- `resetSearchTermOnBlur`: Whether to reset the searchTerm when the Combobox input blurred (type `boolean`; default ``true``; optional)
- `resetSearchTermOnSelect`: Whether to reset the searchTerm when the Combobox value is selected (type `boolean`; default ``true``; optional)
- `openOnFocus`: Whether to open the combobox when the input is focused (type `boolean`; default ``false``; optional)
- `openOnClick`: Whether to open the combobox when the input is clicked (type `boolean`; default ``false``; optional)
- `ignoreFilter`: When `true`, disable the default filters (type `boolean`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? string[] : string)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? string[] : string)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the ComboboxRoot component.
- `update:modelValue`: No description. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `update:open`: Emitted when the open state changes. (type `[value: boolean]`; parameters `value: boolean`)

### ComboboxSeparator

#### Props
Properties for the ComboboxSeparator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxTrigger

#### Props
Properties for the ComboboxTrigger component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxValue

#### Props
Properties for the ComboboxValue component.
- `items`: Items used to resolve selected labels. (type `ComboboxOptionData[]`; optional)
- `placeholder`: Placeholder rendered when no value is selected. (type `string`; optional)
- `separator`: Separator used to join multiple selected labels. (type `string`; default ``', '``; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ComboboxViewport

#### Props
Properties for the ComboboxViewport component.
- `nonce`: Nonce. (type `string`; optional)

### ComboboxVirtualizer

#### Props
Properties for the ComboboxVirtualizer component.
- `options`: List of items (type `string[]`; required)
- `overscan`: Number of items rendered outside the visible area (type `number`; optional)
- `estimateSize`: Estimated size (in px) of each item (type `number | ((index: number) => number)`; optional)
- `textContent`: Text content for each item to achieve type-ahead feature (type `((option: string) => string)`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI builds combobox by reusing the listbox base plus Popper positioning: `ComboboxRoot` (selection state + `useControllableState(open)` + three-state filter) → `ComboboxInput` (`role="combobox"` + `aria-autocomplete`) → `ComboboxTrigger` → `ComboboxContentImpl` (DismissableLayer + FocusScope + bodyLock) → `ComboboxItem` → `ListboxItem`. The `scv()` recipe `comboboxVariants` declares 16 slots and 7 size variants. This mirrors reka-ui / shadcn combobox semantics, with virtual scrolling and the data-driven compact API as SoybeanUI differentiators.

| Capability                      | SoybeanUI | reka-ui `Combobox` | shadcn `Combobox` | Ant Design `Select` (showSearch) |
| :------------------------------ | :-------: | :----------------: | :---------------: | :------------------------------: |
| headless/styled split           |    ✅     |         ✅         |         —         |                —                 |
| Type-to-filter + 3-state filter |    ✅     |         ✅         |        ✅         |                ✅                |
| combobox/listbox roles          |    ✅     |         ✅         |        ✅         |                ✅                |
| Keyboard nav + typeahead        |    ✅     |         ✅         |         —         |                ✅                |
| Virtual scrolling               |    ✅     |         ✅         |         —         |                ✅                |
| Grouping + group labels         |    ✅     |         ✅         |        ✅         |                ✅                |
| Cancel button (clear)           |    ✅     |         ✅         |        ✅         |                ✅                |
| Empty state                     |    ✅     |         ✅         |         —         |                —                 |
| Data-driven Compact API         |    ✅     |         —          |         —         |                —                 |
| axe-clean (open state)          |    ✅     |         —          |        ✅         |                —                 |

### Cautions

- The input filters options client-side; for remote/async filtering, disable built-in filtering or debounce `inputValueChange` yourself.
- `resetSearchTermOnBlur` controls whether the search term is kept after blur — set it to match your UX (e.g. `false` keeps the typed term).
- When the root is `disabled`, all items become unselectable — including items that declare their own `disabled` (unified `rootDisabled || item.disabled` guard).

## FAQ

### What is the difference between `SCombobox` and `SSelect`?

`SCombobox` filters options as the user types (`role="combobox"` + `aria-autocomplete`); `SSelect` is trigger-driven with typeahead only. Choose combobox when typing to search matters.

### How do I enable virtual scrolling for large lists?

Add a `ComboboxVirtualizer` (or the equivalent compact flag) in the content; it activates an internal virtual list while preserving keyboard navigation.

### How do I clear the selection or just the search term?

Pass `clearable`. With a selected value, the trigger shows an ✕ clear icon — clicking it deselects and emits an empty `modelValue` (`undefined`, or `[]` when `multiple`). Inside the popup, the cancel button clears only the search input, keeping the selection.

### Why is a disabled item still selectable?

This was a real bug (a Vue `withDefaults` Boolean-prop defaulting issue) and is fixed. Disabled items now honor the unified `rootDisabled || item.disabled` guard, matching `SSelect`.

## Command

- Page URL: /components/command
- Markdown URL: /components/command.md
- Description: Fast, composable, command menu for Vue. SCommand is a searchable command palette built on the headless listbox primitives with Fuse fuzzy matching. It delegates filtering, grouped item aggregation, and default item composition to the headless CommandCompact; the UI wrapper only injects styles.

# Command

## Overview

Fast, composable, command menu for Vue. `SCommand` is a searchable command palette built on the headless listbox primitives with Fuse fuzzy matching. It delegates filtering, grouped item aggregation, and default item composition to the headless `CommandCompact`; the UI wrapper only injects styles.

Use a command for a ⌘K-style palette, searchable menus, or inline typeahead. For a plain action menu use `dropdown-menu`; for a compact single-select list use `select`.

## Usage

Usage examples for command are rendered on the site.

> `SCommand` now delegates filtering, grouped item aggregation, and default item composition to headless `CommandCompact`. For unstyled, data-driven usage, import `CommandCompact` from `@soybeanjs/headless/command`.

## Features

- 🔎 Fuzzy search — Fuse-powered matching over `label`/`groupLabel`/`description` with configurable `fuseOptions` (threshold, `resultLimit`, match-all-on-empty)
- 🧩 Headless/styled split — `CommandCompact` owns filtering, grouping and item composition; `SCommand` only injects styles
- 📊 Grouped data — `items` with nested group `items` (label/value/icon/description/disabled/separator) and flat items
- 🔍 Item descriptions — `description` renders as a secondary line under the label and is searchable by the built-in filter
- 🚀 External filtering — `external-filter` bypasses the built-in fuzzy filter so items can be filtered and ranked by an external engine (e.g. full-text content search)
- ⌨️ Keyboard nav — full listbox roving focus (arrow keys), selection and `highlight`/`select` events
- 🏷️ Icons + shortcuts — `icon` per item and `shortcut` rendered as a `Kbd`
- 🧹 Clearable — `clearable` shows a trailing clear control; `placeholder`/`emptyLabel` localize the empty state
- 🔒 Disabled — `disabled` disables the input and blocks selection
- ♿ Accessible — `role="listbox"`/`option`, `aria-label`d list, labelled input, `axe-core` clean

## Component family

- `SCommand` (styled) — the entry wrapper; `commandVariants` recipe with dynamic slot forwarding
- `CommandCompact` (headless) — the aggregated composite; owns search, grouping, filtering and default item composition
- `ListboxRoot`/`ListboxFilter`/`ListboxContent`/`ListboxGroup`/`ListboxGroupLabel`/`ListboxItem` (headless) — the underlying listbox primitives
- `Kbd` (headless) — renders item `shortcut`s

## Demos

Interactive demos for command are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (8): Command, CommandCompact, CommandDescription, CommandEmpty, CommandItemContent, CommandItemLabel, CommandSeparator, CommandShortcut.

### Command

#### Props
Properties for the Command component.
- `class`: Root class. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<CommandUi>`; optional)
- `items`: Items rendered by the component. (type `CommandOptionData<T>[]`; required)
- `placeholder`: Placeholder. (type `string`; optional)
- `searchTerm`: Search term. (type `string`; optional)
- `externalFilter`: Whether the items are already filtered and ranked by an external engine (e.g. full-text content search). When true, the built-in fuzzy filter is skipped and all `items` render as-is; `searchTerm` still syncs via `update:searchTerm` so the caller can drive its own search. (type `boolean`; optional)
- `clearable`: Whether clearable. (type `boolean`; optional)
- `fuseOptions`: Fuse options. (type `UseFuseOptions<CommandSearchOptionData<T>>`; optional)
- `listProps`: Properties forwarded to the list element. (type `CommandListProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `CommandItemProps`; optional)
- `itemLabelProps`: Properties forwarded to the item label element. (type `CommandItemLabelProps`; optional)
- `itemContentProps`: Properties forwarded to the item content element (wraps label + description). (type `CommandItemContentProps`; optional)
- `itemDescriptionProps`: Properties forwarded to the item description element. (type `CommandDescriptionProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `CommandGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `CommandGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `CommandShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `CommandSeparatorProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `CommandInputProps`; optional)
- `emptyProps`: Properties forwarded to the empty element. (type `CommandEmptyProps`; optional)
- `emptyLabel`: Empty label. (type `string`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `string`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `string`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `false`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `orientation`: The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Command component.
- `update:modelValue`: No description. (type `[value: string]`; parameters `value: string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `entryFocus`: Event handler called when container is being focused. Can be prevented. (type `[event: CustomEvent<any>]`; parameters `event: CustomEvent<any>`)
- `leave`: Event handler called when the mouse leave the container (type `[event: Event]`; parameters `event: Event`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)
- `update:searchTerm`: Emitted when the search term value changes. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the Command component.
- `input-leading`: Custom content for the input leading slot. (type `((props: CommandCompactInputSlotProps) => any) | undefined`)
- `input-trailing`: Custom content for the input trailing slot. (type `((props: CommandCompactInputSlotProps) => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `(() => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `item-label`: Custom content for the item label slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `item-description`: Custom content for the item description slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `bottom`: Custom content for the bottom slot. (type `(() => any) | undefined`)

### CommandCompact

#### Props
Properties for the CommandCompact component.
- `items`: Items rendered by the component. (type `CommandOptionData<T>[]`; required)
- `placeholder`: Placeholder. (type `string`; optional)
- `searchTerm`: Search term. (type `string`; optional)
- `externalFilter`: Whether the items are already filtered and ranked by an external engine (e.g. full-text content search). When true, the built-in fuzzy filter is skipped and all `items` render as-is; `searchTerm` still syncs via `update:searchTerm` so the caller can drive its own search. (type `boolean`; optional)
- `clearable`: Whether clearable. (type `boolean`; optional)
- `fuseOptions`: Fuse options. (type `UseFuseOptions<CommandSearchOptionData<T>>`; optional)
- `listProps`: Properties forwarded to the list element. (type `CommandListProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `CommandItemProps`; optional)
- `itemLabelProps`: Properties forwarded to the item label element. (type `CommandItemLabelProps`; optional)
- `itemContentProps`: Properties forwarded to the item content element (wraps label + description). (type `CommandItemContentProps`; optional)
- `itemDescriptionProps`: Properties forwarded to the item description element. (type `CommandDescriptionProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `CommandGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `CommandGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `CommandShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `CommandSeparatorProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `CommandInputProps`; optional)
- `emptyProps`: Properties forwarded to the empty element. (type `CommandEmptyProps`; optional)
- `emptyLabel`: Empty label. (type `string`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `string`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `string`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `false`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `disabled`: When `true`, prevents the user from interacting with listbox (type `boolean`; optional)
- `dir`: The reading direction of the listbox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `orientation`: The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `highlightOnHover`: When `true`, hover over item will trigger highlight (type `boolean`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the CommandCompact component.
- `update:modelValue`: No description. (type `[value: string]`; parameters `value: string`)
- `highlight`: Event handler when highlighted element changes. (type `[payload?: CollectionItemData<ListboxCollectionItemData> | undefined]`; parameters `payload?: CollectionItemData<ListboxCollectionItemData> | undefined`)
- `entryFocus`: Event handler called when container is being focused. Can be prevented. (type `[event: CustomEvent<any>]`; parameters `event: CustomEvent<any>`)
- `leave`: Event handler called when the mouse leave the container (type `[event: Event]`; parameters `event: Event`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectEvent<string>]`; parameters `event: SelectEvent<string>`)
- `update:searchTerm`: Emitted when the search term value changes. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the CommandCompact component.
- `input-leading`: Custom content for the input leading slot. (type `((props: CommandCompactInputSlotProps) => any) | undefined`)
- `input-trailing`: Custom content for the input trailing slot. (type `((props: CommandCompactInputSlotProps) => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `(() => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `item-label`: Custom content for the item label slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `item-description`: Custom content for the item description slot. (type `((props: CommandCompactItemSlotProps<T>) => any) | undefined`)
- `bottom`: Custom content for the bottom slot. (type `(() => any) | undefined`)

### CommandDescription

- No documented props, emits, slots, or slot props were available.

### CommandEmpty

- No documented props, emits, slots, or slot props were available.

### CommandItemContent

- No documented props, emits, slots, or slot props were available.

### CommandItemLabel

- No documented props, emits, slots, or slot props were available.

### CommandSeparator

#### Props
Properties for the CommandSeparator component.
- `orientation`: Orientation of the component. Either `vertical` or `horizontal`. Defaults to `horizontal`. (type `DataOrientation`; optional)
- `decorative`: Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. (type `boolean`; optional)

### CommandShortcut

#### Props
Properties for the CommandShortcut component.
- `symbolize`: Whether to convert the command value to symbol representation. (type `boolean`; default `true`; optional)

## Notes

### Architecture and benchmark differences

`CommandCompact` owns the Fuse search, grouped-item aggregation and default item composition while the underlying listbox primitives stay style-free and only the UI wrapper injects the `commandVariants` classes. This mirrors the cmdk/shadcn-ui headless command split. Ant Design, Element Plus, Mantine and Naive UI ship a select/autocomplete rather than a dedicated command palette; SoybeanUI provides a true `⌘K`-style command with Fuse fuzzy search, grouped data, icons/shortcuts, and full listbox keyboard behavior.

| Capability            | SoybeanUI | shadcn/ui (cmdk) | Ant Design | Element Plus | Mantine | Naive UI |
| :-------------------- | :-------: | :--------------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split |    ✅     |        ✅        |     —      |      —       |    —    |    —     |
| Fuzzy search (Fuse)   |    ✅     |        ✅        |     —      |      —       |    —    |    —     |
| Grouped data          |    ✅     |        ✅        |     ✅     |      ✅      |   ✅    |    ✅    |
| Icons + shortcuts     |    ✅     |        ✅        |     —      |      —       |   ✅    |    —     |
| Keyboard nav          |    ✅     |        ✅        |     ✅     |      ✅      |   ✅    |    ✅    |
| Empty state           |    ✅     |        ✅        |     ✅     |      ✅      |   ✅    |    ✅    |

`—` = unsupported or a different interaction model.

### Cautions

- `searchTerm` is controllable via `v-model:searchTerm`; filtering is performed by Fuse (default `threshold: 0.1`, `resultLimit: 12`, match-all on empty).
- `items` accepts grouped objects (`items` nested) and flat items; `separator: true` renders a divider after a group/item.
- `shortcut` renders as a `Kbd` (e.g. `['command', 'h']`); `icon` renders a leading icon.
- `clearable` shows a trailing clear control that resets `searchTerm`; the empty state uses the localized `command.noResults` message.
- The underlying listbox handles keyboard/roving focus; selection emits `select` and `update:modelValue`.

### Roadmap

N/A — command is feature-complete for the current parity set.

## FAQ

### How do I build a command palette?

Pass `items` and a `placeholder`:

```vue

```

### How do I group items?

Nest `items` under a group object with a `separator`:

```vue

```

### How do I control the search term?

Bind `searchTerm` with `v-model:searchTerm` and tune `fuse-options`:

```vue

```

### How do I show an empty state?

Set `empty-label` (falls back to the localized `command.noResults`):

```vue

```

### How do I handle selection?

Listen to `select` and `update:modelValue`:

```vue
<SCommand :items="items" @select="value => run(value)" />
```

### How do I show an item description?

Add a `description` to the item — it renders as a secondary line under the label and is included in the built-in fuzzy filter:

```vue

```

### How do I use an external search engine instead of the built-in filter?

Set `external-filter`: the built-in fuzzy filter is skipped and `items` render as-is (preserving your ranking). `searchTerm` still syncs via `v-model:searchTerm` / `update:searchTerm` so you can drive your own search — for example a full-text content search:

```vue

```

## ConfigProvider

- Page URL: /components/config-provider
- Markdown URL: /components/config-provider.md
- Description: The SConfigProvider component is the root configuration provider for the SoybeanUI library. It manages global themes, localization, icon settings, and other context-aware features. It should wrap your entire application or specific sections that require isolated configuration.

# ConfigProvider

## Overview

The `SConfigProvider` component is the root configuration provider for the SoybeanUI library. It manages global themes, localization, icon settings, and other context-aware features. It should wrap your entire application or specific sections that require isolated configuration.

## Features

- 🎨 **Theme System**: Configure global colors and radius via `theme` prop.
- 📏 **Size Control**: Manage global component sizing (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`).
- 🖼️ **Icon Configuration**: Set default width and height for all `SIcon` components.
- ⏳ **Loading Bar Integration**: Configure the global top loading bar.
- 🍞 **Toast Integration**: Configure global toast settings.
- 🌐 **Direction**: Support for LTR/RTL layouts.
- 🌍 **Locale**: Drive built-in component messages via `locale` and `messages` props.

## Basic Usage

Wrap your application root with `SConfigProvider`.

```vue
<script setup lang="ts">
import { SConfigProvider } from '@soybeanjs/ui';
</script>

<template>
  <SConfigProvider
    size="md"
    :theme="{
      base: 'gray',
      primary: 'violet',
      radius: '0.625rem'
    }"
    :iconify="{ width: '1.25em', height: '1.25em' }"
    dir="ltr"
  >
    <App />
  </SConfigProvider>
</template>
```

## Advanced Theme Configuration

You can fully customize the theme using the `theme` prop. more details can be found in the [theming documentation](/overview/theming).

## Direction / RTL

Use the `dir` prop to switch the supported components between left-to-right and right-to-left layouts.

```vue
<template>
  <SConfigProvider dir="rtl">
    <App />
  </SConfigProvider>
</template>
```

Set `dir="ltr"` explicitly if you want to force left-to-right behavior inside a subtree.

## Locale / Internationalization

SoybeanUI ships with built-in component message sets for the following locales. These messages drive component-level text such as aria-labels and empty-state copy.

| Code    | Language            |
| ------- | ------------------- |
| `zh-CN` | Simplified Chinese  |
| `zh-TW` | Traditional Chinese |
| `en`    | English             |
| `ar`    | Arabic              |
| `ja`    | Japanese            |
| `ko`    | Korean              |
| `de`    | German              |
| `fr`    | French              |
| `es`    | Spanish             |
| `pt-BR` | Portuguese (Brazil) |
| `ru`    | Russian             |
| `tr`    | Turkish             |
| `id`    | Indonesian          |

Only `en` and `zh-CN` are pre-registered by default. Other supported locale files can be imported from `@soybeanjs/headless/locale/{code}` and registered manually.

When `dir` is omitted, `ConfigProvider` automatically follows the direction implied by `locale`. For example, `locale="ar"` resolves to `dir="rtl"`, while `locale="en"` resolves to `dir="ltr"`. Pass `dir` explicitly if you need to override that mapping.

### Switching to a pre-registered locale

Pass the locale code directly to `SConfigProvider`:

```vue

  

```

### Loading another supported locale

`registerLocale` accepts two forms:

- `registerLocale(localeRegistry)` for built-in locale files or any custom registry object when you need explicit `name` and `dir` metadata.
- `registerLocale(key, messages)` for a lightweight custom locale keyed only by its message table.

Import the locale file as a default export, register it once during app setup, and then pass the same locale code to `SConfigProvider`:

```ts
import { registerLocale } from '@soybeanjs/headless/locale';
import ar from '@soybeanjs/headless/locale/ar';

registerLocale(ar);
```

```vue

  

```

Supported locale files are also available at `@soybeanjs/headless/locale/{code}` if you want to extend one as the base for your own custom locale.

### Overriding individual messages

Use the `messages` prop to replace only the keys you need. Keys not listed fall back to the selected built-in locale.

```vue
<script setup lang="ts">
import type { LocaleMessagesOverrides } from '@soybeanjs/headless';

const messages: LocaleMessagesOverrides = {
  table: {
    emptyTitle: 'Nothing here yet',
    emptyDescription: 'Add your first item to get started.'
  }
};
</script>

<template>
  <SConfigProvider locale="en" :messages="messages">
    
  </SConfigProvider>
</template>
```

### Using a custom locale from scratch

Import `en` as a base registry, override any keys from `en.messages`, then register under a custom locale key with the shorthand form:

```ts
import { registerLocale, en } from '@soybeanjs/headless/locale';
import type { LocaleMessages } from '@soybeanjs/headless/locale';

const myLocale: LocaleMessages = {
  ...en.messages,
  pagination: {
    ...en.messages.pagination,
    nextPage: 'Next →',
    prevPage: '← Prev'
  }
};

registerLocale('custom', myLocale);
```

Then pass `locale="custom"` to `SConfigProvider`. If you also need a custom display name or explicit `dir`, pass a full `LocaleRegistry` object to `registerLocale(...)` instead.

### Locale key reference

#### `pagination`

| Key         | Default (en)    | Description                                                       |
| ----------- | --------------- | ----------------------------------------------------------------- |
| `firstPage` | `First page`    | Headless-label and default slot text for the first-page button    |
| `prevPage`  | `Previous page` | Headless-label and default slot text for the previous-page button |
| `nextPage`  | `Next page`     | Headless-label and default slot text for the next-page button     |
| `lastPage`  | `Last page`     | Headless-label and default slot text for the last-page button     |

#### `table`

| Key                | Default (en)                             | Placeholders | Description                                         |
| ------------------ | ---------------------------------------- | ------------ | --------------------------------------------------- |
| `emptyTitle`       | `No data`                                | —            | Title in the default empty slot                     |
| `emptyDescription` | `There is no data to display.`           | —            | Description in the default empty slot               |
| `selectAllRows`    | `Select all rows`                        | —            | Headless-label for the header "select all" checkbox |
| `sortByColumn`     | `Sort by {column}`                       | `{column}`   | Sort button label with no active sort               |
| `sortByColumnAsc`  | `Sort by {column}, currently ascending`  | `{column}`   | Sort button label when ascending                    |
| `sortByColumnDesc` | `Sort by {column}, currently descending` | `{column}`   | Sort button label when descending                   |
| `resizeColumn`     | `Resize {column} column`                 | `{column}`   | Headless-label for the column resize handle         |
| `expandRow`        | `Expand row {row}`                       | `{row}`      | Headless-label for expanding a row                  |
| `collapseRow`      | `Collapse row {row}`                     | `{row}`      | Headless-label for collapsing a row                 |
| `selectRow`        | `Select row {row}`                       | `{row}`      | Headless-label for the row selection checkbox       |

### Fallback rules

1. A key from user-supplied `messages` is used first.
2. If absent, the built-in messages for `locale` are used.
3. If `locale` is unknown or unset, `en` is the final fallback.

### First-batch supported components

The following components respect `ConfigProvider.locale` and `ConfigProvider.messages` in this release:

- **Pagination** — navigation button labels
- **Table** — empty state, sort/resize/expand/select aria-labels

Additional components will be added in future releases following the same pattern.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): ConfigProvider.

### ConfigProvider

#### Props
Properties for the ConfigProvider component.
- `theme`: The theme options. (type `ConfigProviderThemeOptions`; optional)
- `size`: The size options. (type `ThemeSize`; optional)
- `iconify`: The iconify options. (type `IconifyOptions`; optional)
- `progress`: The global top progress configuration of your application. (type `Partial<ProgressProviderProps>`; optional)
- `toast`: The global toast configuration of your application. This will be inherited by the related components. (type `Partial<ToastProviderProps>`; optional)
- `customToast`: Whether to use custom toast rendering. If set to `true`, the `ToastProvider` will not render the default toast UI, and you can import `ToastProvider` component to render custom toast UI. (type `boolean`; default `false`; optional)
- `persistTheme`: Whether to enable persisted theme reading from localStorage. When disabled (default), the ConfigProvider only consumes the explicit `theme` prop and never reads or writes any storage, keeping the current behavior. When enabled, the persisted theme envelope fills in keys not explicitly provided by `theme`, and changes are written back through a single debounced writer. (type `boolean`; default `false`; optional)
- `themeConfig`: The persisted theme envelope injected from the server. Used during SSR to render the same theme the client persisted; on the client the localStorage envelope is the source of truth. (type `ThemeEnvelopeInput`; optional)
- `presetProvider`: The server-side custom theme preset registry resolver. Maps a stored preset name to its definition so SSR can render custom presets without localStorage access. Only used when `persistTheme` is enabled on the server; on the client the presets table (carried by the theme envelope) is the source of truth. (type `((name: string) => ThemePresetColors | null)`; optional)
- `isServer`: Whether the component is running in a server environment. The UI library is pre-built, so `import.meta.env.SSR` is baked at build time and cannot detect the consumer's runtime. This defaults to runtime detection (`typeof window === 'undefined'`), and can be overridden with the app's own flag (e.g. Nuxt's `import.meta.server`) when the app is bundled for both server and client. (type `boolean`; default `isServerRuntime()`; optional)
- `dir`: The global reading direction of your application. This will be inherited by all components. When omitted, the direction follows the current locale and falls back to `'ltr'`. (type `Direction`; optional)
- `locale`: The global locale of your application. This will be inherited by all components. (type `string`; default `'en'`; optional)
- `nonce`: The global `nonce` value of your application. This will be inherited by the related components. (type `string`; optional)
- `tooltip`: The global tooltip configuration of your application. This will be inherited by the related components. (type `Partial<TooltipProviderProps>`; optional)
- `iconRender`: A function to render the icon. This is useful when you want to use a custom icon library or want to wrap the icon with a custom component. (type `((icon: IconValue) => VNode)`; optional)
- `linkComponent`: The component used by `Link` to render internal links. This is useful when you want to integrate a framework-specific link component (e.g. Nuxt `NuxtLink`, a custom `RouterLink` wrapper, or a locale-prefixing `Link`) instead of the globally registered `RouterLink`. When omitted, `Link` resolves the global `RouterLink` and falls back to a native `<a>`. (type `Component`; optional)
- `messages`: Overrides for built-in component locale messages. Merged on top of the locale selected by the `locale` prop, so you only need to supply the keys you want to change. (type `LocaleMessagesOverrides`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits `ConfigProvider` into a headless layer (`@soybeanjs/headless/config-provider`) that owns locale, direction, tooltip, and message context, and a styled layer (`@soybeanjs/ui`) that owns theme CSS injection, icon rendering, and provider composition (toast / dialog / progress). This mirrors `shadcn/ui`'s headless/styled separation and differs from single-package providers such as Ant Design, Element Plus, MUI, Mantine, and Naive UI.

| Aspect               | SoybeanUI                                                                                                | Ant Design / Element Plus / MUI / Mantine / Naive UI  |
| :------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
| Architecture         | headless + styled split, dual `provide/inject` contexts                                                  | single package, single ConfigProvider                 |
| Theme injection      | `buildThemeCss()` (`@soybeanjs/ui` → `@soybeanjs/theme`) written into a `<style id="soybean-theme">` tag | CSS variables / theme object / `ConfigProvider.theme` |
| Dark mode            | `theme.darkSelector` (`'class'` → `.dark`, `'media'` → OS, custom); toggle `.dark` class                 | `theme.dark`, `dark-mode` class, `colorScheme`        |
| RTL                  | `dir` prop + `useDirection`; auto-derived from `locale` with RTL prefix fallback                         | `direction` prop, `dir` attribute, theme direction    |
| i18n                 | `locale` + `messages` overrides; `registerLocale` for additional locales                                 | `locale` prop / `LocalizationProvider`                |
| Provider composition | renders `ToastProvider`, `DialogProvider`, `ProgressProvider` inside the default slot                    | separate providers mounted by the user                |

### Runtime cautions

- **SSR**: the theme never renders into the component tree — the provider owns a real `<head>` element (`<style id="soybean-theme">`, created at mount or adopted from the first-paint script) and keeps its content in sync, so there is no server/client style-content mismatch. The first paint carries the correct theme because the static default block ships with the UnoCSS preset (zero-specificity `:where()` layers) and the init script applies the persisted snapshot before the browser paints. `SIcon` receives `ssr: import.meta.env.SSR` so icon rendering is SSR-safe.
- **Style tag lifecycle**: the `<style id="soybean-theme">` (theme) and `<style id="__SoybeanHeadless_Styles">` (headless layer) tags persist in `<head>` for the lifetime of the page. They are reactive — changing the `theme` prop updates the CSS content in place. Unmounting the provider does not remove them (they are global by design).
- **Locale registration**: only `en` and `zh-CN` are pre-registered. For any other locale (e.g. `ar`, `ja`, `fr`), import the locale file from `@soybeanjs/headless/locale/{code}` and call `registerLocale(...)` once during app setup. Direction (`dir`) falls back to a built-in RTL prefix map (`ar`, `he`, `fa`, `ur`, …) even before a locale is registered, so `locale="ar"` resolves to `dir="rtl"` out of the box.
- **Nesting**: `SConfigProvider` can be nested. An inner provider overrides the outer context for its subtree. The headless and UI contexts are independent injection keys, so headless-only consumers (e.g. `useDirection`) read the headless context while UI consumers (e.g. `SIcon` iconify defaults) read the UI context.

### SSR theme consistency (no flash on refresh)

The theme is persisted in `localStorage` only (no cookie). A client-only style injection would apply the saved theme only after hydration, flashing the default theme on refresh. `@soybeanjs/theme` ships an SSR-safe init script (under the `@soybeanjs/theme/ssr` subpath) that applies the saved theme before first paint:

- **`createThemeInitScript()`** — returns a small IIFE to inline in `<head>`. Before first paint it reads the theme envelope from `localStorage`, toggles the dark class on `<html>` (resolving `mode: 'auto'` against `prefers-color-scheme`), sets `color-scheme`, and patches the snapshot into the `<style id="soybean-theme">` element. The server renders the default theme; the script corrects it before the browser paints, so there is no flash. A payload written by an older vocabulary is migrated on read, and its snapshot (engine output of that older vocabulary) is dropped — the provider re-emits it on mount.
- **`readThemeEnvelope()` / `writeThemeEnvelope()` / `clearThemeEnvelope()`** — explicit persistence helpers, plus `parseThemeEnvelope()` (validate/migrate a raw string), `parseThemeOptions()` (validate just the options) and `createThemeWriter()` (the debounced single writer) — all under the `@soybeanjs/theme/storage` subpath.

In Nuxt the wiring is minimal:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      // apply the saved theme before first paint
      script: [{ innerHTML: createThemeInitScript(), tagPosition: 'head' }]
    }
  }
});
```

```vue
// app.vue — pass only the environment flag
<script setup lang="ts">
import { SConfigProvider } from '@soybeanjs/ui';

const isServer = import.meta.server;
</script>

<template>
  <SConfigProvider :is-server="isServer" persist-theme>
    <slot />
  </SConfigProvider>
</template>
```

`SConfigProvider` reads the persisted theme from `localStorage` on the client; on the server it starts from the default and the inline script corrects it before first paint. Theme state (base / primary / radius / size / mode) and custom presets are managed inside the provider and exposed to descendants via `useTheme()` from `@soybeanjs/ui` — no prop drilling, no app-level store.

### FAQ

**Where should I place `SConfigProvider`?**
Wrap your application root once, typically in `App.vue` or the root layout. It must be an ancestor of every component that relies on theme, locale, direction, toast, dialog, or progress context.

**How do `dir` and `locale` interact?**
`dir` takes precedence when provided explicitly. When omitted, `ConfigProvider` derives direction from `locale`: registered locales use their declared `dir`; unregistered locales fall back to a built-in RTL prefix map (e.g. `ar` → `rtl`, `en` → `ltr`). If `locale` is also unknown, the final fallback is `ltr`.

**How do I add a locale that is not pre-registered?**
Import the locale file and register it once: `registerLocale(ar)` (full registry form) or `registerLocale('custom', messages)` (shorthand form). Then pass `locale="ar"` (or your custom key) to `SConfigProvider`. See the "Loading another supported locale" section above.

**How does dark mode work?**
The engine always generates both light and dark CSS variable sets. The `theme.darkSelector` option controls how the dark set is scoped: `'class'` (default) emits the dark variables under a `.dark` selector, `'media'` emits them under `@media (prefers-color-scheme: dark)`, and any custom string is used verbatim as the selector. With the default `'class'` selector, toggle a `.dark` class on `<html>` (or any ancestor) to switch to dark mode; with `'media'`, the theme follows the user's OS preference automatically.

**Can I nest `SConfigProvider` instances?**
Yes. Nesting is supported — the inner provider's context overrides the outer for its subtree. This is useful for embedding an RTL section inside an LTR app, or a differently-themed micro-frontend.

**How do I render my own toast UI?**
Pass `customToast` to opt out of the default `ToastProvider`: `<SConfigProvider customToast>`. Then import `SToastProvider` (or the headless `ToastProvider`) yourself and render custom toast content. The `toast()` imperative API still works because the headless toast state is independent of the rendered UI.

## ContextMenu

- Page URL: /components/context-menu
- Markdown URL: /components/context-menu.md
- Description: Displays a menu located at the pointer, triggered by a right-click. SContextMenu is a data-driven menu built on the shared headless menu primitives, opening at the pointer position via the contextmenu event (or a press-and-hold on touch, after pressOpenDelay). The family also ships checkbox (SContextMenuCheckbox), radio (SContextMenuRadio) and custom (SContextMenuWrapper) variants.

# ContextMenu

## Overview

Displays a menu located at the pointer, triggered by a right-click. `SContextMenu` is a data-driven menu built on the shared headless menu primitives, opening at the pointer position via the `contextmenu` event (or a press-and-hold on touch, after `pressOpenDelay`). The family also ships checkbox (`SContextMenuCheckbox`), radio (`SContextMenuRadio`) and custom (`SContextMenuWrapper`) variants.

Use a context menu for pointer-relative actions (files, canvas, tree nodes). For a button-triggered menu use `dropdown-menu`; for a rich hover preview use `hover-card`.

## Usage

Usage examples for context-menu are rendered on the site.

## Features

- 🖱️ Right-click trigger — opens at the pointer via the `contextmenu` event; `event.preventDefault()` prevents the native menu
- 📱 Press-and-hold — `pressOpenDelay` (default 700ms) opens on long-press for touch/pen
- 🧩 Headless/menu based — built on the shared menu primitives with full keyboard navigation, typeahead and roving focus
- 📊 Data-driven — pass `items` (with `value`/`label`/`icon`/`disabled`/`hidden`/`separator`…) or use the item slots
- 🙈 Hidden items — an item flagged `hidden` (and its whole subtree) is dropped from the menu
- ☑️ Checkbox / 🔘 Radio variants — `SContextMenuCheckbox`/`SContextMenuRadio` for selectable menus
- 🧩 Wrapper variant — `SContextMenuWrapper` for fully custom menu content
- 🎭 Modal — `modal` controls outside-pointer blocking and focus trapping
- ♿ Accessible — `role="menu"`/`menuitem`, `aria-checked` on checkbox/radio, `axe-core` clean

## Component family

- `SContextMenu` (styled) — the data-driven menu; forwards to `ContextMenuCompact`
- `SContextMenuCheckbox` / `SContextMenuRadio` (styled) — selectable menus with `v-model`
- `SContextMenuWrapper` (styled) — custom-content menu
- `ContextMenuCompact` / `ContextMenuWrapperCompact` / `ContextMenuCheckboxCompact` / `ContextMenuRadioCompact` (headless) — the aggregated composites
- `ContextMenuRoot` / `ContextMenuTrigger` / `ContextMenuContent` (headless) — the pointer-anchored trigger and menu surface
- `MenuOptions`/`MenuItem`/… (headless) — the shared menu primitives

## Demos

Interactive demos for context-menu are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (26): ContextMenu, ContextMenuAnchor, ContextMenuArrow, ContextMenuCheckbox, ContextMenuCheckboxCompact, ContextMenuCheckboxGroup, ContextMenuCheckboxItem, ContextMenuCompact, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuItemIndicator, ContextMenuPortal, ContextMenuRadio, ContextMenuRadioCompact, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuRoot, ContextMenuSeparator, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, ContextMenuWrapper, ContextMenuWrapperCompact.

### ContextMenu

#### Props
Properties for the ContextMenu component.
- `class`: class of menu popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ContextMenuUi>`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `ContextMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `ContextMenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `ContextMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ContextMenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ContextMenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `ContextMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `ContextMenuSubContentProps`; optional)
#### Emits
Events for the ContextMenu component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the ContextMenu component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### ContextMenuAnchor

- No documented props, emits, slots, or slot props were available.

### ContextMenuArrow

- No documented props, emits, slots, or slot props were available.

### ContextMenuCheckbox

#### Props
Properties for the ContextMenuCheckbox component.
- `class`: class of menu popup (type `((string | false | Record<string, any> | ClassValue[]) & (string | false | Record<string, any> | import("vue").ClassV...`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ContextMenuUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuCheckboxOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ContextMenuGroupLabelProps`; optional)
- `checkboxItemProps`: Properties forwarded to the checkbox item element. (type `ContextMenuCheckboxItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ContextMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ContextMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ContextMenuCheckbox component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)
- `select`: Emitted when select occurs. (type `[item: MenuCheckboxOptionData<T>, event: Event]`; parameters `item: MenuCheckboxOptionData<T>, event: Event`)
#### Slots
Slots for the ContextMenuCheckbox component.
- `item`: Custom content for the item slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### ContextMenuCheckboxCompact

#### Props
Properties for the ContextMenuCheckboxCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuCheckboxOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ContextMenuGroupLabelProps`; optional)
- `checkboxItemProps`: Properties forwarded to the checkbox item element. (type `ContextMenuCheckboxItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ContextMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ContextMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ContextMenuCheckboxCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)
- `select`: Emitted when select occurs. (type `[item: MenuCheckboxOptionData<T>, event: Event]`; parameters `item: MenuCheckboxOptionData<T>, event: Event`)
#### Slots
Slots for the ContextMenuCheckboxCompact component.
- `item`: Custom content for the item slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### ContextMenuCheckboxGroup

- No documented props, emits, slots, or slot props were available.

### ContextMenuCheckboxItem

- No documented props, emits, slots, or slot props were available.

### ContextMenuCompact

#### Props
Properties for the ContextMenuCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `ContextMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `ContextMenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `ContextMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ContextMenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ContextMenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `ContextMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `ContextMenuSubContentProps`; optional)
#### Emits
Events for the ContextMenuCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the ContextMenuCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### ContextMenuContent

#### Props
Properties for the ContextMenuContent component.
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the ContextMenuContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### ContextMenuGroup

- No documented props, emits, slots, or slot props were available.

### ContextMenuGroupLabel

- No documented props, emits, slots, or slot props were available.

### ContextMenuItem

- No documented props, emits, slots, or slot props were available.

### ContextMenuItemIndicator

- No documented props, emits, slots, or slot props were available.

### ContextMenuPortal

- No documented props, emits, slots, or slot props were available.

### ContextMenuRadio

#### Props
Properties for the ContextMenuRadio component.
- `class`: class of menu popup (type `((string | false | Record<string, any> | ClassValue[]) & (string | false | Record<string, any> | import("vue").ClassV...`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ContextMenuUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuRadioOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ContextMenuGroupLabelProps`; optional)
- `radioItemProps`: Properties forwarded to the radio item element. (type `ContextMenuRadioItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ContextMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ContextMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ContextMenuRadio component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: Exclude<T, undefined> | null]`; parameters `payload: Exclude<T, undefined> | null`)
- `select`: Emitted when select occurs. (type `[item: MenuRadioOptionData<T>, event: Event]`; parameters `item: MenuRadioOptionData<T>, event: Event`)
#### Slots
Slots for the ContextMenuRadio component.
- `item`: Custom content for the item slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### ContextMenuRadioCompact

#### Props
Properties for the ContextMenuRadioCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuRadioOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `ContextMenuGroupLabelProps`; optional)
- `radioItemProps`: Properties forwarded to the radio item element. (type `ContextMenuRadioItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ContextMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `ContextMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ContextMenuRadioCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: Exclude<T, undefined> | null]`; parameters `payload: Exclude<T, undefined> | null`)
- `select`: Emitted when select occurs. (type `[item: MenuRadioOptionData<T>, event: Event]`; parameters `item: MenuRadioOptionData<T>, event: Event`)
#### Slots
Slots for the ContextMenuRadioCompact component.
- `item`: Custom content for the item slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### ContextMenuRadioGroup

- No documented props, emits, slots, or slot props were available.

### ContextMenuRadioItem

- No documented props, emits, slots, or slot props were available.

### ContextMenuRoot

#### Props
Properties for the ContextMenuRoot component.
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the ContextMenuRoot component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### ContextMenuSeparator

- No documented props, emits, slots, or slot props were available.

### ContextMenuSub

- No documented props, emits, slots, or slot props were available.

### ContextMenuSubContent

- No documented props, emits, slots, or slot props were available.

### ContextMenuSubTrigger

- No documented props, emits, slots, or slot props were available.

### ContextMenuTrigger

#### Props
Properties for the ContextMenuTrigger component.
- `reference`: The reference element for the context menu trigger. (type `HTMLElement | null`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ContextMenuWrapper

#### Props
Properties for the ContextMenuWrapper component.
- `class`: class of menu popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ContextMenuUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the ContextMenuWrapper component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### ContextMenuWrapperCompact

#### Props
Properties for the ContextMenuWrapperCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `ContextMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `ContextMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ContextMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `ContextMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `ContextMenuArrowProps`; optional)
- `pressOpenDelay`: The duration from when the trigger is pressed until the menu opens. (type `number`; default `700`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the ContextMenuWrapperCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

## Notes

### Architecture and benchmark differences

The context-menu family composes the shared `menu` primitives inside a pointer-anchored popover portal; the UI wrappers only inject the shared `menuVariants` classes (via `provideMenuUi`) and forward props/slots. This mirrors radix-ui/shadcn-ui's headless menu split. Ant Design, Element Plus, Mantine and Naive UI ship a single styled context-menu (or reuse their dropdown with `trigger="contextmenu"`); SoybeanUI additionally exposes checkbox/radio/wrapper variants, a `size` scale, and full keyboard/typeahead behavior through the shared menu layer.

| Capability             | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :--------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Pointer-positioned     |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |
| Right-click trigger    |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |
| Press-and-hold (touch) |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Checkbox / radio       |    ✅     |    ✅     |     —      |      —       |   ✅    |    —     |
| Keyboard + typeahead   |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Sizes (6)              |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- The menu opens at the pointer via `contextmenu`; `pressOpenDelay` governs touch long-press (default 700ms).
- `SContextMenu` is `modal` by default (`true`); pass `modal={false}` for a lightweight menu.
- `items` is data-driven; use the matching item slots (`item`, `item-leading`, `item-trailing`) for custom rendering.
- Checkbox/radio variants bind selection with `v-model`; radio expects a single value, checkbox an array.
- The menu is rendered through a portal at the pointer position; `event.preventDefault()` on right-click suppresses the native browser menu.

### Roadmap

N/A — context-menu is feature-complete for the current parity set.

## FAQ

### How do I build a basic context menu?

Pass `items` and wrap a trigger region:

```vue

  <div class="target">Right-click here</div>

```

### How do I open on press-and-hold for touch?

Adjust `press-open-delay`:

```vue

  <div class="target">Hold to open</div>

```

### How do I use the checkbox/radio variants?

Use `SContextMenuCheckbox`/`SContextMenuRadio` with `v-model`:

```vue

  <div class="target">Right-click</div>

```

### How do I build a custom menu?

Use `SContextMenuWrapper` with `MenuItem`s:

```vue

  <div class="target">Right-click</div>
  <MenuItem value="a">Item A</MenuItem>
  <MenuItem value="b">Item B</MenuItem>

```

## DateField

- Page URL: /components/date-field
- Markdown URL: /components/date-field.md
- Description: A segmented date input that keeps day, month, year, and optional time values as separate keyboard-editable parts while still submitting a native form value. Use it for compact date entry where typing should be fast — birth dates, expiry dates, or any single date that needs validation against a range. For a date chosen from a calendar popup, prefer SDatePicker; for browsing a calendar grid, use SCalendar.

# DateField

## Overview

A segmented date input that keeps day, month, year, and optional time values as separate keyboard-editable parts while still submitting a native form value. Use it for compact date entry where typing should be fast — birth dates, expiry dates, or any single date that needs validation against a range. For a date chosen from a calendar popup, prefer `SDatePicker`; for browsing a calendar grid, use `SCalendar`.

## Usage

Usage examples for date-field are rendered on the site.

## Features

- 🧩 Segmented input — each date part (day/month/year, optional hour/minute/second/dayPeriod) is an independent editable segment
- ⌨️ Full keyboard editing — arrow keys increment/decrement, typing fills digits, auto-advance to the next segment, Backspace deletes, `Enter`/focus-out commits
- 🎚 Controlled / uncontrolled — `v-model` and `defaultValue` backed by `useControllableState`, plus `update:placeholder`
- ⛓ Range validation — `minValue`/`maxValue`/`isDateUnavailable` drive the `data-invalid` + `aria-invalid` state
- 🕐 Granularity & time — `granularity` (day/hour/minute/second), 12/24-hour `hourCycle`, and `dayPeriod` segments
- 📝 Form native — a visually hidden input (`name`/`required`/`min`/`max`) submits the ISO value with the owning form
- 🚫 Disabled / readonly — both render proper `data-*`/`aria-*` state and block editing
- 🧩 Extensible — `leading`/`trailing` slots plus `ui.root`/`ui.input` class overrides, built on headless `DateFieldRoot`/`DateFieldInput`

## Component family

- `SDateField` — the styled wrapper that forwards props to the headless compact and injects `dateFieldVariants` classes
- `DateFieldCompact` (headless) — data-driven composition of `DateFieldRoot` + per-segment `DateFieldInput`; import from `@soybeanjs/headless/date-field` for unstyled usage
- `DateFieldRoot` / `DateFieldInput` (headless) — the state owner (segments, validation, hidden input) and a single editable segment

## Demos

Interactive demos for date-field are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): DateField, DateFieldCompact, DateFieldInput, DateFieldRoot.

### DateField

#### Props
Properties for the DateField component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DateFieldUi>`; optional)
- `inputProps`: Properties forwarded to the input element. (type `DateFieldInputProps`; optional)
- `id`: Id. (type `string`; optional)
- `granularity`: Granularity. (type `Granularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `step`: Step. (type `DateStep`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `modelValue`: Current model value. (type `DateValue`; optional)
- `defaultValue`: Default value. (type `DateValue`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DateField component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: DateValue | undefined]`; parameters `value: DateValue | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[value: DateValue]`; parameters `value: DateValue`)

### DateFieldCompact

#### Props
Properties for the DateFieldCompact component.
- `inputProps`: Properties forwarded to the input element. (type `DateFieldInputProps`; optional)
- `id`: Id. (type `string`; optional)
- `granularity`: Granularity. (type `Granularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `step`: Step. (type `DateStep`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `modelValue`: Current model value. (type `DateValue`; optional)
- `defaultValue`: Default value. (type `DateValue`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DateFieldCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: DateValue | undefined]`; parameters `value: DateValue | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[value: DateValue]`; parameters `value: DateValue`)

### DateFieldInput

#### Props
Properties for the DateFieldInput component.
- `part`: Part. (type `import("../../date").EditableSegmentPart | import("../../date").NonEditableSegmentPart`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### DateFieldRoot

#### Props
Properties for the DateFieldRoot component.
- `id`: Id. (type `string`; optional)
- `granularity`: Granularity. (type `Granularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `step`: Step. (type `DateStep`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `modelValue`: Current model value. (type `DateValue`; optional)
- `defaultValue`: Default value. (type `DateValue`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DateFieldRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: DateValue | undefined]`; parameters `value: DateValue | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[value: DateValue]`; parameters `value: DateValue`)
#### Slots
Slots for the DateFieldRoot component.
- `default`: No description. (type `((props: DateFieldRootSlotProps) => any) | undefined`)
#### Slot Props
Properties for the DateFieldRoot slot.
- `modelValue`: Current model value. (type `DateValue | undefined`; required)
- `segments`: Segments used by the default slot. (type `DateFieldSegment[]`; required)
- `isInvalid`: Whether the current value is invalid. (type `boolean`; required)

## Notes

### Architecture and benchmark differences

`DateFieldRoot` owns the value (via `useControllableState`), derives the segment layout with `Intl.DateTimeFormat` formatters, and runs validation through `isInvalid`. Each `DateFieldInput` binds the `useDateField` composable, which implements per-part keydown logic (increment/decrement/typing/auto-advance/delete) shared by the `time-field` family. Editing mutates a `segmentValues` shallowRef; the root commits the assembled `DateValue` once every segment is filled. The segmented date-field pattern originates from reka-ui (Radix); the benchmark libraries express date input as a plain text input plus a picker popup instead.

| Capability                  | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :-------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split       |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Segmented editable parts    |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled   |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Keyboard increment/typing   |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Auto-advance between parts  |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Range validation            |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isDateUnavailable`         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Granularity (minute/second) |    ✅     |     —      |      —       |    —    |    —     |   —    |
| 12/24-hour `dayPeriod`      |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Disabled / readonly         |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Native form submission      |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `leading`/`trailing` slots  |    ✅     |     —      |      —       |    —    |    —     |   —    |

### Cautions

- A segment is committed as soon as every part is filled; deleting the last digit emits `update:modelValue` with `undefined`.
- `defaultValue` is only read on mount — use `v-model` for external control.
- The root uses `role="group"` and each editable part `role="spinbutton"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`; add `aria-label` to the field so screen readers announce the whole control.
- Form submission requires `name`; `required`/`min`/`max` are reflected on the hidden input but do not run custom validation.
- `granularity="day"` renders `type="date"`; time granularities render `type="datetime-local"` on the hidden input.
- `readonly` differs from `disabled`: the field stays focusable and visible but blocks editing.

## FAQ

### How do I clear the value?

Backspace on a single-digit segment (or Backspace twice on a two-digit segment) empties it and emits `update:modelValue` with `undefined` — handle the `undefined` in the parent. The segments then fall back to placeholder styling.

### How do I restrict the selectable range?

Pass `minValue`/`maxValue` — the field marks itself `data-invalid` (plus `aria-invalid` on segments) when the value falls outside. `isDateUnavailable` accepts a predicate for arbitrary exclusions.

### How do I use 12-hour time?

Pass `hourCycle={12}` (or let it follow the locale) — the hour segment becomes 1–12 and a `dayPeriod` (AM/PM) segment appears. Arrow keys and `a`/`p` keys toggle the period.

### What is the difference between `SDateField` and `SDatePicker`?

`SDateField` is a pure segmented input with no popup — best for fast typing and form submission. `SDatePicker` embeds a `DateField` alongside a calendar popover for visual selection.

### How do I customize the look?

Use `ui.root`/`ui.input` for class overrides, or `leading`/`trailing` slots to place icons/units around the segments. For fully unstyled control, compose `DateFieldRoot`/`DateFieldInput` from `@soybeanjs/headless/date-field`.

## DatePicker

- Page URL: /components/date-picker
- Markdown URL: /components/date-picker.md
- Description: A date picker that pairs a keyboard-editable segmented date field with a calendar popup for visual selection. Type a date directly into the segments or click the calendar toggle to pick from a month grid. Use it whenever a user must choose a single date — booking, scheduling, filtering, or any form that needs a validated date range. For pure typing with no popup, prefer SDateField; for browsing a standalone calendar grid, use SCalendar.

# DatePicker

## Overview

A date picker that pairs a keyboard-editable segmented date field with a calendar popup for visual selection. Type a date directly into the segments or click the calendar toggle to pick from a month grid. Use it whenever a user must choose a single date — booking, scheduling, filtering, or any form that needs a validated date range. For pure typing with no popup, prefer `SDateField`; for browsing a standalone calendar grid, use `SCalendar`.

## Usage

Usage examples for date-picker are rendered on the site.

## Features

- 📅 Field + popup combo — the segmented `DateField` stays editable while a calendar popover offers visual selection
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` for the value plus `open`/`defaultOpen` for the popup, both backed by `useControllableState`
- ⌨️ Full keyboard editing — segment increment/decrement/typing in the field, arrow-key grid navigation in the calendar, `Escape` closes
- ⛓ Range validation — `minValue`/`maxValue`/`isDateUnavailable` disable out-of-range and unavailable days in both the field and the calendar
- 🌍 Locale-aware accessibility — default `aria-label`s for the calendar toggle and popup dialog come from the active locale messages and are overridable via `triggerProps`/`popupProps`
- 🧩 Composable slots — `leading` for content before the segments, `default` slot props expose `open`/`close`/`calendarProps` for a fully custom popup
- 🎨 Fine-grained styling — `ui` covers the field plus `trigger`/`positioner`/`popup` slots, and `calendarUi` targets the embedded calendar independently
- 🚫 Disabled state — `disabled` blocks both field editing and popup opening

## Component family

- `SDatePicker` — the styled wrapper that forwards props to the headless compact, injects `datePickerVariants` (extending `dateFieldVariants`), and renders `SCalendar` inside the popup
- `DatePickerCompact` (headless) — data-driven composition of `DateFieldCompact` + `PopoverCompact` (calendar-icon trigger) that exposes the popup state and `calendarProps` through its default slot; import from `@soybeanjs/headless/date-picker` for unstyled usage
- `DateFieldCompact` / `PopoverCompact` / `CalendarCompact` (headless) — the segmented field, the popover mechanics, and the calendar grid that back the picker

## Demos

Interactive demos for date-picker are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (2): DatePicker, DatePickerCompact.

### DatePicker

#### Props
Properties for the DatePicker component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DatePickerUi>`; optional)
- `calendarUi`: Per-slot class overrides for the Calendar component within the DatePicker. (type `Partial<CalendarUi>`; optional)
- `dateFieldProps`: No description. (type `BaseProps`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopperPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CalendarHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarPrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarCellTriggerProps`; optional)
- `locale`: Locale. (type `string`; optional)
- `modelValue`: Current model value. (type `DateValue`; optional)
- `defaultValue`: Default value. (type `DateValue`; optional)
- `multiple`: Whether multiple values are supported. (type `false`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DatePicker component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
- `update:modelValue`: Emitted when the model value changes. (type `[date: DateValue | undefined]`; parameters `date: DateValue | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
#### Slots
Slots for the DatePicker component.
- `leading`: Custom content rendered before the date segments. (type `(() => any) | undefined`)

### DatePickerCompact

#### Props
Properties for the DatePickerCompact component.
- `dateFieldProps`: No description. (type `BaseProps`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopperPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CalendarHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarPrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarCellTriggerProps`; optional)
- `locale`: Locale. (type `string`; optional)
- `modelValue`: Current model value. (type `DateValue`; optional)
- `defaultValue`: Default value. (type `DateValue`; optional)
- `multiple`: Whether multiple values are supported. (type `false`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DatePickerCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
- `update:modelValue`: Emitted when the model value changes. (type `[date: DateValue | undefined]`; parameters `date: DateValue | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
#### Slots
Slots for the DatePickerCompact component.
- `leading`: Custom content rendered before the date segments. (type `(() => any) | undefined`)
- `default`: Custom content for the calendar popup, receiving the open/close controls and calendar props. (type `((props: DatePickerCompactSlotProps) => any) | undefined`)
#### Slot Props
- `open`: No description. (type `boolean`; required)
- `close`: No description. (type `() => void`; required)
- `calendarProps`: No description. (type `CalendarCompactProps<false>`; required)
- `onUpdateModelValue`: No description. (type `(value: DateValue | undefined) => void`; required)
- `onUpdatePlaceholder`: No description. (type `(placeholder: DateValue) => void`; required)

## Notes

### Architecture and benchmark differences

`SDatePicker` forwards props to `DatePickerCompact`, which wires `DateFieldCompact` (segments + validation) and `PopoverCompact` (a `lucide:calendar` icon trigger with `aria-haspopup="dialog"`). The styled layer injects `datePickerVariants` classes through `provideDatePickerUi` so the nested popover parts get `trigger`/`positioner`/`popup` styling, then renders `SCalendar` in the default slot with the forwarded `calendarProps`. Selecting a day emits `update:modelValue` and closes the popup. The popup is a `role="dialog"` with a default accessible name from the locale `popupLabel` message; the toggle gets `toggle`. Most benchmark libraries ship a plain text input plus a picker panel; the segmented-field-plus-popover combo and the headless/styled split are the differentiators.

| Capability                       | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :------------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split            |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Segmented field + calendar popup |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled value  |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Controlled / uncontrolled open   |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Keyboard segment editing         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Calendar keyboard navigation     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   ✅   |
| Range validation                 |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isDateUnavailable`              |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Disabled state                   |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Locale-driven accessible names   |    ✅     |     —      |      —       |    —    |    —     |   —    |
| `leading` slot                   |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Independent `calendarUi`         |    ✅     |     —      |      —       |    —    |    —     |   —    |

### Cautions

- The value is a `DateValue` (`Date` or `{ date, time? }`) — not a `string`. Use it with `SDateField`, `SCalendar`, and the other date-family components.
- `defaultValue`/`defaultOpen` are only read on mount — use `v-model`/`open` for external control.
- The toggle button is the calendar icon; its default `aria-label` (locale `toggle`) can be overridden through `triggerProps['aria-label']`. The icon itself is fixed — to render a custom trigger, compose `DatePickerCompact` from `@soybeanjs/headless/date-picker` with your own popover content.
- The popup `role="dialog"` gets its accessible name from the locale `popupLabel` message; override it through `popupProps['aria-label']`.
- Pass `dateFieldProps` (e.g. `placeholder`, `locale`, `granularity`) to configure the embedded segmented field; field and calendar share `minValue`/`maxValue`/`isDateUnavailable`.
- `calendarUi` is consumed by the embedded calendar and never reaches the DOM — the same applies to `dateFieldProps`.

## FAQ

### How do I choose a date with the keyboard?

Tab into the segmented field and type digits or use arrow keys, or press the calendar toggle and navigate the month grid with arrow keys, `Home`/`End` and `PageUp`/`PageDown`; `Enter` selects and closes, `Escape` closes without selecting.

### How do I restrict the selectable range?

Pass `minValue`/`maxValue` — out-of-range days are disabled in the calendar and the field marks itself `data-invalid`. `isDateUnavailable` accepts a predicate for arbitrary exclusions and applies to both the field and the calendar.

### How do I configure the embedded date field?

Use `dateFieldProps` — for example `{ placeholder }`, `{ locale }`, `{ granularity: 'minute' }` or `{ hourCycle: 12 }`. The field accepts the same props as `SDateField` itself.

### How do I customize the calendar look?

`calendarUi` overrides the calendar's per-slot classes independently of `ui`. For deeper customization, the default slot receives `calendarProps` (plus `open`/`close`) so you can render your own popup content with `CalendarCompact` from `@soybeanjs/headless/calendar`.

### How is `SDatePicker` different from `SDateField`?

`SDateField` is a pure segmented input with no popup — fastest for typing and form submission. `SDatePicker` adds the calendar popover on top of the same field, trading a little footprint for visual selection.

## DateRangeField

- Page URL: /components/date-range-field
- Markdown URL: /components/date-range-field.md
- Description: A segmented date range input that renders two groups of keyboard-editable date segments — one for the start date and one for the end date — while submitting native form values for both. Use it whenever a user must enter a bounded interval fast, such as booking stay dates, reporting windows, or filter ranges where typing beats calendar clicking. For a range chosen from a calendar popup, prefer SDateRangePicker; for a single date, use SDateField.

# DateRangeField

## Overview

A segmented date range input that renders two groups of keyboard-editable date segments — one for the start date and one for the end date — while submitting native form values for both. Use it whenever a user must enter a bounded interval fast, such as booking stay dates, reporting windows, or filter ranges where typing beats calendar clicking. For a range chosen from a calendar popup, prefer `SDateRangePicker`; for a single date, use `SDateField`.

## Usage

Usage examples for date-range-field are rendered on the site.

## Features

- 🧩 Dual segmented groups — independent start and end segment groups (day/month/year, optional time), each part an editable `role="spinbutton"` segment
- ⌨️ Cross-group focus movement — arrow keys navigate within a group, and at the group edges `ArrowLeft`/`ArrowRight` move focus into the other group, with directions reversed in RTL
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` accept a `DateRange` `{ start, end }`, backed by `useControllableState`
- ⛓ Range validation — `minValue`/`maxValue`/`isDateUnavailable` per date, and a start later than end automatically marks the root `data-invalid`
- 📝 Dual native form values — two visually hidden inputs (`startName`/`endName`, falling back to `name` for the start) submit the ISO values
- 🕐 Granularity & time — `granularity` (day/hour/minute/second), 12/24-hour `hourCycle`, and `dayPeriod` segments apply to both groups
- 🧩 Customizable separation — a `separator` prop (default `–`) plus `leading`/`trailing` slots, or a `separator` slot for fully custom content
- 🚫 Disabled / readonly — both states render proper `data-*`/`aria-*` attributes and block editing across both groups

## Component family

- `SDateRangeField` — the styled wrapper that forwards props to the headless compact and injects `dateRangeFieldVariants` (extending `dateFieldVariants`) classes
- `DateRangeFieldCompact` (headless) — data-driven composition of `DateRangeFieldRoot` + per-segment `DateRangeFieldInput` for both groups, plus `leading`/`trailing`/`separator` slots; import from `@soybeanjs/headless/date-range-field` for unstyled usage
- `DateRangeFieldRoot` / `DateRangeFieldInput` (headless) — the state owner (dual segment values, validation, hidden inputs, cross-group focus) and a single editable segment bound to the shared `useDateField` composable

## Demos

Interactive demos for date-range-field are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): DateRangeField, DateRangeFieldCompact, DateRangeFieldInput, DateRangeFieldRoot.

### DateRangeField

#### Props
Properties for the DateRangeField component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DateRangeFieldUi>`; optional)
- `inputProps`: Properties forwarded to the input element. (type `DateRangeFieldInputProps`; optional)
- `separator`: Separator. (type `string`; optional)
- `defaultValue`: Default value. (type `DateRange`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `startName`: Start name. (type `string`; optional)
- `endName`: End name. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `granularity`: Granularity. (type `Granularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
#### Emits
Events for the DateRangeField component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
- `update:endValue`: Emitted when the end value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the DateRangeField component.
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `(() => any) | undefined`)
#### Slot Props
Slot properties for the DateRangeField component.
- `startSegments`: Start segments used by the component context. (type `DateFieldSegment[]`; required)
- `endSegments`: End segments used by the component context. (type `DateFieldSegment[]`; required)
- `modelValue`: Current model value. (type `DateRange`; required)
- `isInvalid`: Whether the date is invalid. (type `boolean`; required)

### DateRangeFieldCompact

#### Props
Properties for the DateRangeFieldCompact component.
- `inputProps`: Properties forwarded to the input element. (type `DateRangeFieldInputProps`; optional)
- `separator`: Separator. (type `string`; optional)
- `defaultValue`: Default value. (type `DateRange`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `startName`: Start name. (type `string`; optional)
- `endName`: End name. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `granularity`: Granularity. (type `Granularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
#### Emits
Events for the DateRangeFieldCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
- `update:endValue`: Emitted when the end value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the DateRangeFieldCompact component.
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `(() => any) | undefined`)

### DateRangeFieldInput

#### Props
Properties for the DateRangeFieldInput component.
- `type`: Type. (type `DateRangeType`; optional)
- `part`: Part. (type `import("../../date").EditableSegmentPart | import("../../date").NonEditableSegmentPart`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### DateRangeFieldRoot

#### Props
Properties for the DateRangeFieldRoot component.
- `defaultValue`: Default value. (type `DateRange`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `startName`: Start name. (type `string`; optional)
- `endName`: End name. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `granularity`: Granularity. (type `Granularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
#### Emits
Events for the DateRangeFieldRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
- `update:endValue`: Emitted when the end value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the DateRangeFieldRoot component.
- `default`: Custom content for the default slot. (type `((props: DateRangeFieldSlotProps) => any) | undefined`)

## Notes

### Architecture and benchmark differences

`DateRangeFieldRoot` owns the `{ start, end }` value via `useControllableState`, keeps separate `startSegmentValues`/`endSegmentValues` shallowRefs for the two groups, and runs validation through `isInvalid` (including a start-later-than-end check). Each `DateRangeFieldInput` binds the same `useDateField` composable used by the `time-field` family for per-part keydown logic. Cross-group movement is handled by the root's `moveFocus`: at the physical end of the start group the next arrow moves into the end group, and at the beginning of the end group the previous arrow returns, with the physical key mapped from the `dir` so RTL swaps `ArrowLeft`/`ArrowRight`. Most benchmark libraries implement a range as two separate text inputs or one text input with a separator; the dual segmented-field pattern with cross-group keyboard focus comes from the reka-ui (Radix) date-field lineage.

| Capability                     | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :----------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split          |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Dual segmented editable groups |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Cross-group focus movement     |    ✅     |     —      |      —       |    —    |    —     |   —    |
| RTL direction reversal         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled      |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Keyboard increment/typing      |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Range validation (start ≤ end) |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isDateUnavailable`            |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Granularity (minute/second)    |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Dual native form values        |    ✅     |     ✅     |      ✅      |   ✅    |    —     |   —    |
| Disabled / readonly            |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Separator prop / slot          |    ✅     |     —      |      —       |    —    |    —     |   —    |

### Cautions

- The value is a `DateRange` — an object `{ start, end }` of `DateValue`s, not a `string`. Use it with the other date-family components.
- `defaultValue` is only read on mount — use `v-model` for external control.
- A start later than end is marked invalid but the values are never swapped automatically — clear or correct them in the parent.
- Form submission uses two hidden inputs: the start one takes `startName` (or the shared `name`), the end one takes `endName`. Set both to submit distinct fields; `required`/`min`/`max` are reflected but do not run custom validation.
- Deleting the last digit of one group emits `update:modelValue` with that side `undefined`; segments fall back to placeholder styling.
- Each group renders `role="group"` with per-segment `role="spinbutton"`; add an `aria-label` to the whole control so screen readers announce both groups.

## FAQ

### How do I move focus between the two groups with the keyboard?

Use `ArrowLeft`/`ArrowRight` — at the first segment of the end group `ArrowLeft` jumps to the last start segment, and at the last segment of the start group `ArrowRight` jumps to the first end segment. In RTL the physical keys are reversed.

### How do I submit two form values?

Pass `name` (fallback for the start) plus `startName` and `endName` for distinct field names — each group renders a visually hidden native input carrying its ISO value.

### How do I restrict the selectable range?

Pass `minValue`/`maxValue` — dates outside are marked `data-invalid` and rejected. `isDateUnavailable` accepts a predicate for arbitrary exclusions, and a start later than end is invalid on its own.

### How is `SDateRangeField` different from `SDateRangePicker`?

`SDateRangeField` is a pure dual segmented input with no popup — fastest for typing and form submission. `SDateRangePicker` adds a calendar popover on top of the same field for visual selection.

### How do I customize the separator?

Pass `separator` (e.g. `"→"`) to change the text, or use the `separator` slot to render anything (an icon, a styled label). `leading`/`trailing` slots place content around the two groups.

## DateRangePicker

- Page URL: /components/date-range-picker
- Markdown URL: /components/date-range-picker.md
- Description: A date range picker that pairs a keyboard-editable dual segmented date range field with a calendar range popup for visual selection. Type a start and end date directly into the segments or click the calendar toggle and pick both ends from a single month-range grid. Use it whenever a user must choose a bounded interval — booking stay dates, reporting windows, or filter ranges. For pure typing with no popup, prefer SDateRangeField; for a single date with a popup, use SDatePicker.

# DateRangePicker

## Overview

A date range picker that pairs a keyboard-editable dual segmented date range field with a calendar range popup for visual selection. Type a start and end date directly into the segments or click the calendar toggle and pick both ends from a single month-range grid. Use it whenever a user must choose a bounded interval — booking stay dates, reporting windows, or filter ranges. For pure typing with no popup, prefer `SDateRangeField`; for a single date with a popup, use `SDatePicker`.

## Usage

Usage examples for date-range-picker are rendered on the site.

## Features

- 📅 Dual field + popup combo — the segmented `DateRangeField` stays editable while a `CalendarRange` popover offers visual selection of both dates
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` for the value plus `open`/`defaultOpen` for the popup, both backed by `useControllableState`
- ⌨️ Full keyboard editing — segment increment/decrement/typing in both groups, cross-group arrow movement, arrow-key grid navigation in the calendar, `Escape` closes
- ⛓ Range validation — `minValue`/`maxValue`/`isDateUnavailable` disable out-of-range and unavailable days in both the field and the calendar
- 🌍 Locale-aware accessibility — default `aria-label`s for the calendar toggle and popup dialog come from the active locale messages and are overridable via `triggerProps`/`popupProps`
- 🧩 Composable slots — `leading` for content before the segments and `separator` for a custom divider; the default slot exposes `open`/`close`/`calendarRangeProps` for a fully custom popup
- 🎨 Fine-grained styling — `ui` covers the field plus `trigger`/`positioner`/`popup` slots, and `calendarRangeUi` targets the embedded calendar independently
- 🚫 Disabled state — `disabled` blocks both field editing and popup opening

## Component family

- `SDateRangePicker` — the styled wrapper that forwards props to the headless compact, injects `dateRangePickerVariants` (extending `dateFieldVariants`), and renders `SCalendarRange` inside the popup
- `DateRangePickerCompact` (headless) — data-driven composition of `DateRangeFieldCompact` + `PopoverCompact` (calendar-icon trigger) that exposes the popup state and `calendarRangeProps` through its default slot; import from `@soybeanjs/headless/date-range-picker` for unstyled usage
- `DateRangeFieldCompact` / `PopoverCompact` / `CalendarRangeCompact` (headless) — the dual segmented field, the popover mechanics, and the range calendar grid that back the picker

## Demos

Interactive demos for date-range-picker are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (2): DateRangePicker, DateRangePickerCompact.

### DateRangePicker

#### Props
Properties for the DateRangePicker component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DateRangePickerUi>`; optional)
- `calendarRangeUi`: Per-slot class overrides for the CalendarRange component within the DateRangePicker. (type `Partial<CalendarRangeUi>`; optional)
- `dateFieldProps`: No description. (type `BaseProps`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopperPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CalendarRangeHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarRangeHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarRangePrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarRangeNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarRangeGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarRangeGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarRangeGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarRangeGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarRangeHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarRangeCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarRangeCellTriggerProps`; optional)
- `defaultValue`: Default value. (type `DateRange`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `allowNonContiguousRanges`: Whether to allow non contiguous ranges. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `maximumDays`: Maximum days. (type `number`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `locale`: Locale. (type `string`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `isDateHighlightable`: Whether a date highlightable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `fixedDate`: Fixed date. (type `'start' | 'end'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DateRangePicker component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the DateRangePicker component.
- `leading`: Custom content rendered before the date range segments. (type `(() => any) | undefined`)
- `separator`: Custom content rendered between the start and end segment groups. (type `(() => any) | undefined`)

### DateRangePickerCompact

#### Props
Properties for the DateRangePickerCompact component.
- `dateFieldProps`: No description. (type `BaseProps`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopperPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `headerProps`: Properties forwarded to the header element. (type `CalendarRangeHeaderProps`; optional)
- `headingProps`: Properties forwarded to the heading element. (type `CalendarRangeHeadingProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `CalendarRangePrevProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `CalendarRangeNextProps`; optional)
- `gridProps`: Properties forwarded to the grid element. (type `CalendarRangeGridProps`; optional)
- `gridHeadProps`: Properties forwarded to the grid head element. (type `CalendarRangeGridHeadProps`; optional)
- `gridBodyProps`: Properties forwarded to the grid body element. (type `CalendarRangeGridBodyProps`; optional)
- `gridRowProps`: Properties forwarded to the grid row element. (type `CalendarRangeGridRowProps`; optional)
- `headCellProps`: Properties forwarded to the head cell element. (type `CalendarRangeHeadCellProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `CalendarRangeCellProps`; optional)
- `cellTriggerProps`: Properties forwarded to the cell trigger element. (type `CalendarRangeCellTriggerProps`; optional)
- `defaultValue`: Default value. (type `DateRange`; optional)
- `defaultPlaceholder`: Default placeholder. (type `DateValue`; optional)
- `placeholder`: Placeholder. (type `DateValue`; optional)
- `modelValue`: Current model value. (type `DateRange`; optional)
- `allowNonContiguousRanges`: Whether to allow non contiguous ranges. (type `boolean`; optional)
- `pagedNavigation`: Whether paged navigation. (type `boolean`; optional)
- `preventDeselect`: Whether prevent deselect. (type `boolean`; optional)
- `maximumDays`: Maximum days. (type `number`; optional)
- `weekStartsOn`: Week starts on. (type `WeekStartsOn`; optional)
- `weekdayFormat`: Weekday format. (type `WeekDayFormat`; optional)
- `calendarLabel`: Calendar label. (type `string`; optional)
- `fixedWeeks`: Whether fixed weeks. (type `boolean`; optional)
- `maxValue`: Max value. (type `DateValue`; optional)
- `minValue`: Min value. (type `DateValue`; optional)
- `locale`: Locale. (type `string`; optional)
- `numberOfMonths`: Number of months. (type `number`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `initialFocus`: Whether initial focus. (type `boolean`; optional)
- `isDateDisabled`: Whether the date is disabled. (type `DateMatcher`; optional)
- `isDateUnavailable`: Whether the date is unavailable. (type `DateMatcher`; optional)
- `isDateHighlightable`: Whether a date highlightable. (type `DateMatcher`; optional)
- `nextPage`: Next page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `prevPage`: Prev page. (type `((placeholder: DateValue) => DateValue)`; optional)
- `disableDaysOutsideCurrentView`: Whether to disable days outside current view. (type `boolean`; optional)
- `fixedDate`: Fixed date. (type `'start' | 'end'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DateRangePickerCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
- `update:modelValue`: Emitted when the model value changes. (type `[range: DateRange]`; parameters `range: DateRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[date: DateValue]`; parameters `date: DateValue`)
- `update:startValue`: Emitted when the start value changes. (type `[date: DateValue | null]`; parameters `date: DateValue | null`)
#### Slots
Slots for the DateRangePickerCompact component.
- `leading`: Custom content rendered before the date range segments. (type `(() => any) | undefined`)
- `separator`: Custom content rendered between the start and end segment groups. (type `(() => any) | undefined`)
- `default`: Custom content for the calendar range popup, receiving the open/close controls and calendar props. (type `((props: DateRangePickerCompactSlotProps) => any) | undefined`)
#### Slot Props
- `open`: No description. (type `boolean`; required)
- `close`: No description. (type `() => void`; required)
- `calendarRangeProps`: No description. (type `CalendarRangeCompactProps`; required)
- `onUpdateModelValue`: No description. (type `(value: DateRange) => void`; required)
- `onUpdatePlaceholder`: No description. (type `(placeholder: DateValue) => void`; required)

## Notes

### Architecture and benchmark differences

`SDateRangePicker` forwards props to `DateRangePickerCompact`, which wires `DateRangeFieldCompact` (dual segments + validation) and `PopoverCompact` (a `lucide:calendar` icon trigger with `aria-haspopup="dialog"`). The styled layer injects `dateRangePickerVariants` classes through `provideDateRangePickerUi` so the nested popover parts get `trigger`/`positioner`/`popup` styling, then renders `SCalendarRange` in the default slot with the forwarded `calendarRangeProps`. Selecting a start and an end day emits `update:modelValue` and closes the popup once both ends are set. The popup is a `role="dialog"` with a default accessible name from the locale `popupLabel` message; the toggle gets `toggle`. Most benchmark libraries ship two plain text inputs plus a range panel; the dual-segmented-field-plus-popover combo, the cross-group keyboard focus, and the headless/styled split are the differentiators.

| Capability                         | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :--------------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split              |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Dual segmented field + range popup |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled value    |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Controlled / uncontrolled open     |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Keyboard segment editing           |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Cross-group focus movement         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Calendar keyboard navigation       |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   ✅   |
| Range validation                   |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isDateUnavailable`                |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Disabled state                     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Locale-driven accessible names     |    ✅     |     —      |      —       |    —    |    —     |   —    |
| `leading` / `separator` slots      |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Independent `calendarRangeUi`      |    ✅     |     —      |      —       |    —    |    —     |   —    |

### Cautions

- The value is a `DateRange` — an object `{ start, end }` of `DateValue`s, not a `string`. Use it with `SDateRangeField`, `SCalendarRange`, and the other date-family components.
- `defaultValue`/`defaultOpen` are only read on mount — use `v-model`/`open` for external control.
- The toggle button is the calendar icon; its default `aria-label` (locale `toggle`) can be overridden through `triggerProps['aria-label']`. The icon itself is fixed — to render a custom trigger, compose `DateRangePickerCompact` from `@soybeanjs/headless/date-range-picker` with your own popover content.
- The popup `role="dialog"` gets its accessible name from the locale `popupLabel` message; override it through `popupProps['aria-label']`.
- Pass `dateFieldProps` (e.g. `placeholder`, `locale`, `granularity`) to configure the embedded dual segmented field; field and calendar share `minValue`/`maxValue`/`isDateUnavailable`.
- `calendarRangeUi` is consumed by the embedded calendar and never reaches the DOM — the same applies to `dateFieldProps`.
- A start later than end is marked invalid but the values are never swapped automatically — clear or correct them in the parent.

## FAQ

### How do I choose a date range with the keyboard?

Tab into either segmented group and type digits or use arrow keys, or press the calendar toggle and navigate the month grid with arrow keys, `Home`/`End` and `PageUp`/`PageDown`; `Enter` commits the selection, `Escape` closes without selecting. Both ends must be picked for the value to emit.

### How do I restrict the selectable range?

Pass `minValue`/`maxValue` — out-of-range days are disabled in the calendar and the field marks itself `data-invalid`. `isDateUnavailable` accepts a predicate for arbitrary exclusions and applies to both the field and the calendar.

### How do I configure the embedded date range field?

Use `dateFieldProps` — for example `{ placeholder }`, `{ locale }`, `{ granularity: 'minute' }` or `{ hourCycle: 12 }`. The field accepts the same props as `SDateRangeField` itself.

### How do I customize the calendar look?

`calendarRangeUi` overrides the range calendar's per-slot classes independently of `ui`. For deeper customization, the default slot receives `calendarRangeProps` (plus `open`/`close`) so you can render your own popup content with `CalendarRangeCompact` from `@soybeanjs/headless/calendar-range`.

### How is `SDateRangePicker` different from `SDateRangeField`?

`SDateRangeField` is a pure dual segmented input with no popup — fastest for typing and form submission. `SDateRangePicker` adds the calendar range popover on top of the same field, trading a little footprint for visual selection.

## Dialog

- Page URL: /components/dialog
- Markdown URL: /components/dialog.md
- Description: A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.

# Dialog

## Overview

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.

`SDialog` is the declarative wrapper for inline usage. `dialog(...)` is the imperative API for creating alert-style dialogs programmatically. It combines the `DialogRoot`/`DialogTrigger`/`DialogOverlay`/`DialogPopup`/`DialogHeader`/`DialogContent`/`DialogFooter`/`DialogTitle`/`DialogDescription`/`DialogClose`/`DialogFullscreen`/`DialogCancel`/`DialogConfirm` headless primitive family (zero styles) with the `dialogVariants` style recipe (12 slots, 6 sizes).

Mount `SDialogProvider` once near your app root before calling the imperative `dialog(...)` API.

## Usage

### Declarative

Usage examples for dialog are rendered on the site.

### Imperative API

```vue
<script setup lang="ts">
import { h } from 'vue';
import { SButton, SDialogProvider, dialog } from '@soybeanjs/ui';

function openWarningDialog() {
  dialog.warning('Delete Project', {
    description: 'This action cannot be undone.',
    content: h('div', 'Please confirm before continuing.'),
    confirmText: 'Delete'
  });
}
</script>

<template>
  <SDialogProvider />

  <SButton color="warning" @click="openWarningDialog">Open Dialog</SButton>
</template>
```

## Features

- 🧩 Headless/styled split — `DialogCompact` aggregates the primitives and composes the overlay/popup/header/content/footer; `SDialog` only injects styles and forwards slots/events
- 🖱️ Declarative + imperative — inline `SDialog` with a trigger, or `dialog.*` API driven by `SDialogProvider`
- 🎭 Modal by default — `modal` renders `aria-modal`, `useHideOthers`, outside-pointer blocking and focus trapping; toggle with `modal={false}`
- ⚠️ Alert mode — `isAlert` switches to `role="alertdialog"`, adds the type icon and `aria-live` (`polite`/`assertive`)
- 🏷️ Accessible title/description — `title`/`description` wire `aria-labelledby`/`aria-describedby`
- ❌ Closable — `showClose` renders a close control; Escape, outside pointer/focus and the close button all dismiss
- 🖐️ Draggable — `draggable` lets you move the dialog by dragging its header (powered by `useDraggable` from `@vueuse/core`)
- ⛶ Fullscreen — `showFullscreen` renders a toggle; `fullscreen`/`defaultFullscreen` drive a `v-model:fullscreen` state
- 🔘 Cancel/confirm — `showCancel`/`showConfirm` with localized `cancelText`/`confirmText` from `dialog.cancel`/`dialog.confirm`
- 🧹 Pure mode — `pure` drops the header/footer for fully custom content
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ♿ Accessible — real `role="dialog"`, focus trap + loop, focus restoration on close, `axe-core` zero violations

## Component family

- `SDialog` (styled) — the entry wrapper; `dialogVariants` recipe with dynamic slot forwarding
- `SDialogProvider` (styled) — hosts the imperative `dialog(...)` API; subscribes to `DialogState`
- `DialogRoot` (headless) — the state owner; `open` via `useControllableState`, `dir`/`modal`, `provideDialogRootContext`
- `DialogTrigger` (headless) — a `Button` that opens the dialog
- `DialogOverlay` (headless) — the dimmed backdrop
- `DialogPopup` / `DialogPopupImpl` (headless) — the focus-trapped, dismissable surface hosting the dialog body
- `DialogTitle` / `DialogDescription` (headless) — the labelled/described elements
- `DialogClose` (headless) — the close control, toggles `open` and emits `close`
- `DialogFullscreen` (headless) — the fullscreen toggle, toggles the `fullscreen` state and emits `fullscreen`
- `DialogCancel` / `DialogConfirm` (headless) — footer actions, emit `cancel`/`confirm`
- `DialogHeader` / `DialogContent` / `DialogFooter` (headless) — layout sections
- `DialogCompact` (headless) — the aggregated composite; composes all primitives and exposes the per-part slots

## Demos

Interactive demos for dialog are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (19): Dialog, DialogCancel, DialogClose, DialogCompact, DialogCompactBase, DialogConfirm, DialogContent, DialogDescription, DialogFooter, DialogFullscreen, DialogFullscreenState, DialogHeader, DialogOverlay, DialogPopup, DialogPortal, DialogProvider, DialogRoot, DialogTitle, DialogTrigger.

### Dialog

#### Props
Properties for the Dialog component.
- `showFullscreen`: Whether show the fullscreen toggle button in the header of the dialog. (type `boolean`; default `false`; optional)
- `class`: the popup class of the dialog (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DialogUi>`; optional)
- `title`: The title of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `title` slot is not provided. (type `string`; optional)
- `description`: The description of the dialog. This is used for accessibility purposes and will be rendered in the content of the dialog if the `description` slot is not provided. (type `string`; optional)
- `icon`: The icon of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `icon` slot is not provided. (type `string | import("vue").Component | VNode<import("vue").RendererNode, import("vue").RendererElement, { [key: string]: ...`; optional)
- `showClose`: Whether show the close button in the header of the dialog. (type `boolean`; default `true`; optional)
- `pure`: Whether to use the pure version of the dialog, which does not include the header and footer. This is useful when you want to fully control the content of the dialog and do not need the built-in header and footer. (type `boolean`; default `false`; optional)
- `showCancel`: Whether to show the cancel button. When set to `onlyWarning`, the cancel button will only be shown when the dialog is an alert dialog with `alertType="warning"`. When set to `true`, the cancel button will always be shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `cancelText`: The text of the cancel button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `cancel` slot is not provided. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showConfirm`: Whether to show the confirm button when the dialog is an alert dialog. The default value is `true` when the dialog is an alert dialog. (type `boolean`; optional)
- `confirmText`: The text of the confirm button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `confirm` slot is not provided. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DialogTriggerProps`; optional)
- `overlayProps`: Properties forwarded to the overlay element. (type `DialogOverlayProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DialogPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DialogPopupProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `DialogHeaderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DialogContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `DialogFooterProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `DialogTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `DialogDescriptionProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `DialogCloseProps`; optional)
- `fullscreenProps`: Properties forwarded to the fullscreen element. (type `DialogFullscreenProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `DialogCancelProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `DialogConfirmProps`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. Set to `'trap-focus'` to trap focus while still letting outside pointer events through (non-modal side panels such as `Drawer` in the `'trap-focus'` tier). (type `ModalityTier`; default `true`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
#### Emits
Events for the Dialog component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `close`: Event handler called when the dialog is requested to be closed. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `fullscreen`: Event handler called when the fullscreen state of the dialog is requested to be toggled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
#### Slots
Slots for the Dialog component.
- `default`: Custom content for the default slot. (type `(props: DialogCompactBaseSlotProps) => any`; parameters `props: DialogCompactBaseSlotProps`)
- `trigger`: Custom content for the trigger slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `fullscreen`: Custom content for the fullscreen slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `cancel`: Custom content for the cancel slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `confirm`: Custom content for the confirm slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)

### DialogCancel

#### Props
Properties for the DialogCancel component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DialogCancel component.
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DialogClose

#### Props
Properties for the DialogClose component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DialogClose component.
- `close`: Event handler called when the dialog is requested to be closed. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DialogCompact

#### Props
Properties for the DialogCompact component.
- `title`: The title of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `title` slot is not provided. (type `string`; optional)
- `description`: The description of the dialog. This is used for accessibility purposes and will be rendered in the content of the dialog if the `description` slot is not provided. (type `string`; optional)
- `icon`: The icon of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `icon` slot is not provided. (type `string | import("vue").Component | VNode<import("vue").RendererNode, import("vue").RendererElement, { [key: string]: ...`; optional)
- `showClose`: Whether show the close button in the header of the dialog. (type `boolean`; default `true`; optional)
- `showFullscreen`: Whether show the fullscreen toggle button in the header of the dialog. (type `boolean`; default `true`; optional)
- `pure`: Whether to use the pure version of the dialog, which does not include the header and footer. This is useful when you want to fully control the content of the dialog and do not need the built-in header and footer. (type `boolean`; default `false`; optional)
- `showCancel`: Whether to show the cancel button. When set to `onlyWarning`, the cancel button will only be shown when the dialog is an alert dialog with `alertType="warning"`. When set to `true`, the cancel button will always be shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `cancelText`: The text of the cancel button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `cancel` slot is not provided. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showConfirm`: Whether to show the confirm button when the dialog is an alert dialog. The default value is `true` when the dialog is an alert dialog. (type `boolean`; optional)
- `confirmText`: The text of the confirm button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `confirm` slot is not provided. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DialogTriggerProps`; optional)
- `overlayProps`: Properties forwarded to the overlay element. (type `DialogOverlayProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DialogPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DialogPopupProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `DialogHeaderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DialogContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `DialogFooterProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `DialogTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `DialogDescriptionProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `DialogCloseProps`; optional)
- `fullscreenProps`: Properties forwarded to the fullscreen element. (type `DialogFullscreenProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `DialogCancelProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `DialogConfirmProps`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. Set to `'trap-focus'` to trap focus while still letting outside pointer events through (non-modal side panels such as `Drawer` in the `'trap-focus'` tier). (type `ModalityTier`; default `true`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
#### Emits
Events for the DialogCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `close`: Event handler called when the dialog is requested to be closed. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `fullscreen`: Event handler called when the fullscreen state of the dialog is requested to be toggled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
#### Slots
Slots for the DialogCompact component.
- `default`: Custom content for the default slot. (type `(props: DialogCompactBaseSlotProps) => any`; parameters `props: DialogCompactBaseSlotProps`)
- `trigger`: Custom content for the trigger slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `fullscreen`: Custom content for the fullscreen slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `cancel`: Custom content for the cancel slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `confirm`: Custom content for the confirm slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)

### DialogCompactBase

#### Slot Props
Slot properties for the DialogCompactBase component.
- `open`: Whether the component is open. (type `boolean`; required)
- `close`: Close exposed in the slot scope. (type `() => void`; required)

### DialogConfirm

#### Props
Properties for the DialogConfirm component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DialogConfirm component.
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DialogContent

- No documented props, emits, slots, or slot props were available.

### DialogDescription

- No documented props, emits, slots, or slot props were available.

### DialogFooter

- No documented props, emits, slots, or slot props were available.

### DialogFullscreen

#### Props
Properties for the DialogFullscreen component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DialogFullscreen component.
- `fullscreen`: Event handler called when the fullscreen state of the dialog is requested to be toggled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DialogFullscreenState

#### Emits
Events for the fullscreen state of the dialog. Kept separate from `DialogRootEmits`
because the latter is shared by other disclosure primitives (popover, menu, drawer).
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### DialogHeader

- No documented props, emits, slots, or slot props were available.

### DialogOverlay

#### Props
Properties for the DialogOverlay component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)

### DialogPopup

#### Props
Properties for the DialogPopup component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the DialogPopup component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)

### DialogPortal

- No documented props, emits, slots, or slot props were available.

### DialogProvider

- No documented props, emits, slots, or slot props were available.

### DialogRoot

#### Props
Properties for the DialogRoot component.
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. Set to `'trap-focus'` to trap focus while still letting outside pointer events through (non-modal side panels such as `Drawer` in the `'trap-focus'` tier). (type `ModalityTier`; default `true`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
#### Emits
Events for the DialogRoot component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### DialogTitle

- No documented props, emits, slots, or slot props were available.

### DialogTrigger

#### Props
Properties for the DialogTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DialogTrigger component.
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

## Notes

### Architecture and benchmark differences

`DialogCompact` owns the overlay/popup/header/content/footer composition and the imperative `dialog(...)` state flow while every primitive stays style-free and only the UI wrapper injects the `dialogVariants` classes. This mirrors radix-ui/shadcn-ui's headless/styled split. Ant Design, Element Plus, Mantine and Naive UI ship a single styled dialog with `mask`/`closable`/`keyboard`/`width` props; SoybeanUI additionally exposes a per-slot `*Props` channel, a `size` scale, and an imperative provider API (`dialog.*`) that the single-package libraries fold into a static service.

| Capability                    | SoybeanUI | shadcn/ui | Ant Design Modal | Element Plus Dialog | Mantine Modal | Naive UI Dialog |
| :---------------------------- | :-------: | :-------: | :--------------: | :-----------------: | :-----------: | :-------------: |
| Headless/styled split         |    ✅     |    ✅     |        —         |          —          |       —       |        —        |
| Imperative API                |    ✅     |     —     |        ✅        |         ✅          |      ✅       |       ✅        |
| Modal (aria-modal + trap)     |    ✅     |    ✅     |        ✅        |         ✅          |      ✅       |       ✅        |
| Alert mode (alertdialog)      |    ✅     |    ✅     |        ✅        |          —          |       —       |       ✅        |
| Focus return on close         |    ✅     |    ✅     |        ✅        |         ✅          |      ✅       |       ✅        |
| Sizes (6)                     |    ✅     |     —     |        —         |          —          |       —       |        —        |
| Localized cancel/confirm text |    ✅     |     —     |        —         |          —          |       —       |        —        |
| Pure (no header/footer)       |    ✅     |     —     |        —         |          —          |       —       |        —        |

`—` = unsupported or a different interaction model.

### Cautions

- `DialogCompact` defaults to `modal` (`true`); the portal teleports the popup to `document.body` and the body scroll is managed by the hide-others layer.
- `showConfirm` defaults to `true` when the dialog is an alert; `showCancel` defaults to `'onlyWarning'` (cancel appears only for `alertType="warning"`). Pass an explicit boolean to override.
- `cancelText`/`confirmText` default to the localized `dialog.cancel`/`dialog.confirm` messages; override per instance.
- `isAlert` requires a `DialogTitle` for accessibility (`role="alertdialog"` must be labelled). Set `title` or the `title` slot.
- `pure` removes the header and footer, so `title`/`description` are no longer rendered — provide your own accessible label in that mode.
- The imperative `dialog(...)` API needs `SDialogProvider` mounted; calling it without the provider is a no-op.

## FAQ

### How do I control the open state?

Bind `open` with `v-model`, or pass `defaultOpen` for an uncontrolled dialog:

```vue
<SDialog v-model:open="open" title="Preferences">...</SDialog>
```

### How do I show an alert-style dialog?

Set `is-alert` with an `alert-type`. The popup gets `role="alertdialog"` and the matching type icon:

```vue

  <template #trigger><SButton>Delete</SButton></template>

```

### How do I use the imperative API?

Mount `SDialogProvider` once, then call `dialog.*` from anywhere (see the Overview section for a full example):

```ts
import { dialog } from '@soybeanjs/ui';
dialog.warning('Disk full', { description: 'Free up space.' });
```

### How do I build a fully custom dialog?

Use `pure` and fill the default slot:

```vue

  <div class="custom">...</div>

```

### How do I make a non-modal dialog?

Set `modal={false}` to allow interacting with content outside the dialog:

```vue
<SDialog v-model:open="open" :modal="false" title="Palette">...</SDialog>
```

### How do I make a draggable dialog?

Set `draggable` and drag the header to move the dialog. The position is kept until the dialog is closed:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drag the header to move this dialog.</div>

```

### How do I use the fullscreen mode?

Toggle it with the header button (`showFullscreen`, hidden by default — pass `show-fullscreen` to opt in) or drive it with `v-model:fullscreen`:

```vue
<SDialog v-model:fullscreen="fullscreen" title="Panel">...</SDialog>
```

## Drawer

- Page URL: /components/drawer
- Markdown URL: /components/drawer.md
- Description: A gesture-driven panel that slides in from an edge of the screen. It owns its own headless family — snap points, swipe dismiss, drag handle and nested scaling — built on the dialog primitives for modality, focus and dismissal.

# Drawer

## Overview

A gesture-driven panel that slides in from an edge of the screen. Unlike `SSheet` (a dialog with a side), the drawer owns a real domain state machine: **snap points**, **swipe progress**, a **drag handle**, and **nested scaling** are behaviour the dialog family does not have.

`SDrawer` combines the headless `drawer` primitive family with the `drawerVariants` style recipe (extends `sheetVariants`, adds a drag `handle` and an opt-in `swipeArea`; 6 sizes × 4 sides). Modality, focus trapping and dismissal still come from the shared dialog primitives.

## Usage

Usage examples for drawer are rendered on the site.

## Features

- 🧩 Dialog-backed modality — inherits the dialog contract (`open`/`defaultOpen`, focus trap, focus restoration, Escape/outside dismissal) while adding the drawer state machine
- 🧭 4 sides — `side="top"`/`"bottom"`/`"left"`/`"right"` (default `bottom`); horizontal sides are mirrored under RTL, vertical sides cap their height and scroll their content
- 📏 Snap points — `snapPoints` accepts fractions (`0.5`), pixel offsets or CSS lengths; bind the active level with `v-model:snap-point`; the drawer opens at the first snap point and resets to it when closed
- 🪜 Sequential snapping — `snapToSequentialPoints` walks one level at a time instead of jumping to the nearest point
- 🖐️ Swipe dismiss — dragging the panel or the handle past `closeThreshold` closes it; `dismissible={false}` forces an explicit action; `swipeDirection` overrides the dismiss direction
- 👉 Swipe to open — opt into an edge gesture strip with `swipeable` (`DrawerSwipeArea`), with axis locking, direction damping, sampled velocity and scroll yielding
- 🖼️ Page indent — `DrawerIndent` / `DrawerIndentBackground` scale, shift and round the page behind the drawer following the live swipe progress (CSS-variable driven)
- 🧲 Handle-only dragging — `handleOnly` restricts the gesture to the handle; `fixed` pins the panel while its content scrolls
- 🪗 Nested drawers — `nested` renders through `DrawerRootNested` so drag, release and open state stay coordinated with the parent
- 🎛️ Modality tiers — `modal` accepts `true` (full modal), `'trap-focus'` (focus trapped, outside pointer events alive) or `false`
- 🔘 Dialog footer — `showClose`/`showCancel`/`showConfirm` with localized `cancelText`/`confirmText`
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ⛶ Fullscreen — `fullscreen`/`defaultFullscreen` (or `v-model:fullscreen`) grow the panel to the viewport from its anchored edge; snapping and dragging are suspended while fullscreen
- ♿ Accessible — `role="dialog"`, focus moves into the panel, `axe-core` clean

## Component family

- `SDrawer` (styled) — the entry wrapper; `drawerVariants` recipe with dynamic slot forwarding
- `DrawerRoot` / `DrawerRootNested` (headless) — the state owner; `open`, `snapPoints`, `snapPoint`, `dismissible`, `nested`, drag/swipe state
- `DrawerTrigger` (headless) — the opener, wired to `aria-haspopup`/`aria-expanded`
- `DrawerPortal` (headless) — the teleport boundary
- `DrawerOverlay` (headless) — the dimmed backdrop; fades with the live swipe progress
- `DrawerPopup` (headless) — the focus-trapped surface and the drag gesture host; its position is driven entirely by CSS variables (`--soybean-drawer-snap-point-offset` + `--soybean-drawer-swipe-movement-x/y`)
- `DrawerViewport` (headless) — the scrollable region that carries snap-point state
- `DrawerSwipeArea` (headless) — the opt-in edge strip that opens the drawer by swipe
- `DrawerHandle` (headless) — the grab handle; double-tap cycles snap points. `DrawerCompact` renders it only for `side="bottom"`
- `DrawerIndent` / `DrawerIndentBackground` (headless) — wrap the page behind the drawer to get the indent effect; `data-active` marks an open drawer and `--soybean-drawer-swipe-progress` carries the live progress
- `DrawerHeader` / `DrawerContent` / `DrawerFooter` / `DrawerTitle` / `DrawerDescription` / `DrawerClose` / `DrawerCancel` / `DrawerConfirm` (headless) — chrome primitives wrapping Dialog; DOM uses `data-soybean-drawer-*`
- `DrawerCompact` (headless) — the aggregated composite; composes handle, swipe area, header, content and footer and exposes the slots

## Demos

Interactive demos for drawer are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (21): Drawer, DrawerCancel, DrawerClose, DrawerCompact, DrawerConfirm, DrawerContent, DrawerDescription, DrawerFooter, DrawerHandle, DrawerHeader, DrawerIndent, DrawerIndentBackground, DrawerOverlay, DrawerPopup, DrawerPortal, DrawerRoot, DrawerRootNested, DrawerSwipeArea, DrawerTitle, DrawerTrigger, DrawerViewport.

### Drawer

#### Props
Properties for the Drawer component.
- `description`: The description of the dialog. This is used for accessibility purposes and will be rendered in the content of the dialog if the `description` slot is not provided. (type `string`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `title`: The title of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `title` slot is not provided. (type `string`; optional)
- `icon`: The icon of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `icon` slot is not provided. (type `string | import("vue").Component | VNode<import("vue").RendererNode, import("vue").RendererElement, { [key: string]: ...`; optional)
- `pure`: Whether to use the pure version of the dialog, which does not include the header and footer. This is useful when you want to fully control the content of the dialog and do not need the built-in header and footer. (type `boolean`; default `false`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DrawerPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DrawerPopupProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DialogTriggerProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `DialogHeaderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DialogContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `DialogFooterProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `DialogCloseProps`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `showClose`: Whether show the close button in the header of the dialog. (type `boolean`; default `true`; optional)
- `showFullscreen`: Whether show the fullscreen toggle button in the header of the dialog. (type `boolean`; default `true`; optional)
- `showCancel`: Whether to show the cancel button. When set to `onlyWarning`, the cancel button will only be shown when the dialog is an alert dialog with `alertType="warning"`. When set to `true`, the cancel button will always be shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `cancelText`: The text of the cancel button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `cancel` slot is not provided. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showConfirm`: Whether to show the confirm button when the dialog is an alert dialog. The default value is `true` when the dialog is an alert dialog. (type `boolean`; optional)
- `confirmText`: The text of the confirm button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `confirm` slot is not provided. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `overlayProps`: Properties forwarded to the overlay element. (type `DrawerOverlayProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `DialogTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `DialogDescriptionProps`; optional)
- `fullscreenProps`: Properties forwarded to the fullscreen element. (type `DialogFullscreenProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `DialogCancelProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `DialogConfirmProps`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `modal`: Modality tier. `true` blocks outside pointer events, `'trap-focus'` only traps focus, `false` keeps the surface non-modal. (type `import("../../types").ModalityTier`; default `true`; optional)
- `snapPoint`: The controlled snap point. Can be bound with `v-model:snapPoint`. (type `DrawerSnapPoint | null`; optional)
- `defaultSnapPoint`: The snap point used when the drawer is initially rendered. Use when you do not need to control it. Defaults to the first entry of `snapPoints`. (type `DrawerSnapPoint | null`; optional)
- `snapToSequentialPoints`: When `true`, snaps to the next sequential snap point (one step at a time). When `false`, snaps to the nearest snap point by distance. (type `boolean`; default `false`; optional)
- `closeThreshold`: Close threshold as a fraction of the drawer size (0–1). (type `number`; default `0.25`; optional)
- `swipeDirection`: The swipe direction that dismisses the drawer. Defaults to the direction opposite the drawer's entry edge (`side`). (type `SwipeDirection`; optional)
- `fixed`: Whether fixed. (type `boolean`; optional)
- `dismissible`: Whether dismissible. (type `boolean`; default `true`; optional)
- `nested`: Whether nested. (type `boolean`; default `false`; optional)
- `side`: Direction. (type `Side`; default `'bottom'`; optional)
- `noBodyStyles`: When `true` the `body` doesn't get any styles assigned from the drawer (type `boolean`; optional)
- `handleOnly`: Whether handle only. (type `boolean`; default `false`; optional)
- `preventScrollRestoration`: Whether prevent scroll restoration. (type `boolean`; optional)
- `snapPoints`: Snap points used to position the drawer. Use numbers between 0 and 1 to represent fractions of the viewport height, numbers greater than 1 as pixel values, or strings in `px`/`rem` units. (type `DrawerSnapPoint[]`; optional)
- `handleProps`: Properties forwarded to the handle element. (type `DrawerHandleProps`; optional)
- `swipeable`: Render the opt-in swipe-to-open area at the drawer's edge. (type `boolean`; default `false`; optional)
- `swipeAreaProps`: Properties forwarded to the swipe area element. (type `DrawerSwipeAreaProps`; optional)
- `class`: the popup class of the drawer (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DrawerUi>`; optional)
#### Emits
Events for the Drawer component.
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `fullscreen`: Event handler called when the fullscreen state of the dialog is requested to be toggled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `drag`: Emitted while dragging with the live progress: 0 fully open, 1 closed. (type `[percentageDragged: number]`; parameters `percentageDragged: number`)
- `release`: Emitted when a drag gesture releases; `true` when the drawer stays open. (type `[open: boolean]`; parameters `open: boolean`)
- `close`: Emitted when close occurs. (type `[]`)
- `update:snapPoint`: Emitted when the snap point value changes. (type `[val: DrawerSnapPoint | null]`; parameters `val: DrawerSnapPoint | null`)
#### Slots
Slots for the Drawer component.
- `default`: Custom content for the default slot. (type `(props: DialogCompactBaseSlotProps) => any`; parameters `props: DialogCompactBaseSlotProps`)
- `trigger`: Custom content for the trigger slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `fullscreen`: Custom content for the fullscreen slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `cancel`: Custom content for the cancel slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `confirm`: Custom content for the confirm slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)

### DrawerCancel

#### Props
Properties for the DrawerCancel component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DrawerCancel component.
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DrawerClose

#### Props
Properties for the DrawerClose component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DrawerClose component.
- `close`: Event handler called when the dialog is requested to be closed. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DrawerCompact

#### Props
Properties for the DrawerCompact component.
- `description`: The description of the dialog. This is used for accessibility purposes and will be rendered in the content of the dialog if the `description` slot is not provided. (type `string`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `title`: The title of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `title` slot is not provided. (type `string`; optional)
- `icon`: The icon of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `icon` slot is not provided. (type `string | import("vue").Component | VNode<import("vue").RendererNode, import("vue").RendererElement, { [key: string]: ...`; optional)
- `pure`: Whether to use the pure version of the dialog, which does not include the header and footer. This is useful when you want to fully control the content of the dialog and do not need the built-in header and footer. (type `boolean`; default `false`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DrawerPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DrawerPopupProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DialogTriggerProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `DialogHeaderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DialogContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `DialogFooterProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `DialogCloseProps`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `showClose`: Whether show the close button in the header of the dialog. (type `boolean`; default `true`; optional)
- `showFullscreen`: Whether show the fullscreen toggle button in the header of the dialog. (type `boolean`; default `true`; optional)
- `showCancel`: Whether to show the cancel button. When set to `onlyWarning`, the cancel button will only be shown when the dialog is an alert dialog with `alertType="warning"`. When set to `true`, the cancel button will always be shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `cancelText`: The text of the cancel button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `cancel` slot is not provided. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showConfirm`: Whether to show the confirm button when the dialog is an alert dialog. The default value is `true` when the dialog is an alert dialog. (type `boolean`; optional)
- `confirmText`: The text of the confirm button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `confirm` slot is not provided. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `overlayProps`: Properties forwarded to the overlay element. (type `DrawerOverlayProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `DialogTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `DialogDescriptionProps`; optional)
- `fullscreenProps`: Properties forwarded to the fullscreen element. (type `DialogFullscreenProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `DialogCancelProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `DialogConfirmProps`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `modal`: Modality tier. `true` blocks outside pointer events, `'trap-focus'` only traps focus, `false` keeps the surface non-modal. (type `import("../../types").ModalityTier`; default `true`; optional)
- `snapPoint`: The controlled snap point. Can be bound with `v-model:snapPoint`. (type `DrawerSnapPoint | null`; optional)
- `defaultSnapPoint`: The snap point used when the drawer is initially rendered. Use when you do not need to control it. Defaults to the first entry of `snapPoints`. (type `DrawerSnapPoint | null`; optional)
- `snapToSequentialPoints`: When `true`, snaps to the next sequential snap point (one step at a time). When `false`, snaps to the nearest snap point by distance. (type `boolean`; default `false`; optional)
- `closeThreshold`: Close threshold as a fraction of the drawer size (0–1). (type `number`; default `0.25`; optional)
- `swipeDirection`: The swipe direction that dismisses the drawer. Defaults to the direction opposite the drawer's entry edge (`side`). (type `SwipeDirection`; optional)
- `fixed`: Whether fixed. (type `boolean`; optional)
- `dismissible`: Whether dismissible. (type `boolean`; default `true`; optional)
- `nested`: Whether nested. (type `boolean`; default `false`; optional)
- `side`: Direction. (type `Side`; default `'bottom'`; optional)
- `noBodyStyles`: When `true` the `body` doesn't get any styles assigned from the drawer (type `boolean`; optional)
- `handleOnly`: Whether handle only. (type `boolean`; default `false`; optional)
- `preventScrollRestoration`: Whether prevent scroll restoration. (type `boolean`; optional)
- `snapPoints`: Snap points used to position the drawer. Use numbers between 0 and 1 to represent fractions of the viewport height, numbers greater than 1 as pixel values, or strings in `px`/`rem` units. (type `DrawerSnapPoint[]`; optional)
- `handleProps`: Properties forwarded to the handle element. (type `DrawerHandleProps`; optional)
- `swipeable`: Render the opt-in swipe-to-open area at the drawer's edge. (type `boolean`; default `false`; optional)
- `swipeAreaProps`: Properties forwarded to the swipe area element. (type `DrawerSwipeAreaProps`; optional)
#### Emits
Events for the DrawerCompact component.
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `fullscreen`: Event handler called when the fullscreen state of the dialog is requested to be toggled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `drag`: Emitted while dragging with the live progress: 0 fully open, 1 closed. (type `[percentageDragged: number]`; parameters `percentageDragged: number`)
- `release`: Emitted when a drag gesture releases; `true` when the drawer stays open. (type `[open: boolean]`; parameters `open: boolean`)
- `close`: Emitted when close occurs. (type `[]`)
- `update:snapPoint`: Emitted when the snap point value changes. (type `[val: DrawerSnapPoint | null]`; parameters `val: DrawerSnapPoint | null`)
#### Slots
Slots for the DrawerCompact component.
- `default`: Custom content for the default slot. (type `(props: DialogCompactBaseSlotProps) => any`; parameters `props: DialogCompactBaseSlotProps`)
- `trigger`: Custom content for the trigger slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `fullscreen`: Custom content for the fullscreen slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `cancel`: Custom content for the cancel slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `confirm`: Custom content for the confirm slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)

### DrawerConfirm

#### Props
Properties for the DrawerConfirm component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DrawerConfirm component.
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)

### DrawerContent

- No documented props, emits, slots, or slot props were available.

### DrawerDescription

- No documented props, emits, slots, or slot props were available.

### DrawerFooter

- No documented props, emits, slots, or slot props were available.

### DrawerHandle

#### Props
Properties for the DrawerHandle component.
- `preventCycle`: Whether prevent cycle. (type `boolean`; optional)

### DrawerHeader

- No documented props, emits, slots, or slot props were available.

### DrawerIndent

- No documented props, emits, slots, or slot props were available.

### DrawerIndentBackground

- No documented props, emits, slots, or slot props were available.

### DrawerOverlay

- No documented props, emits, slots, or slot props were available.

### DrawerPopup

- No documented props, emits, slots, or slot props were available.

### DrawerPortal

- No documented props, emits, slots, or slot props were available.

### DrawerRoot

#### Props
Properties for the DrawerRoot component.
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `modal`: Modality tier. `true` blocks outside pointer events, `'trap-focus'` only traps focus, `false` keeps the surface non-modal. (type `import("../../types").ModalityTier`; default `true`; optional)
- `snapPoint`: The controlled snap point. Can be bound with `v-model:snapPoint`. (type `DrawerSnapPoint | null`; optional)
- `defaultSnapPoint`: The snap point used when the drawer is initially rendered. Use when you do not need to control it. Defaults to the first entry of `snapPoints`. (type `DrawerSnapPoint | null`; optional)
- `snapToSequentialPoints`: When `true`, snaps to the next sequential snap point (one step at a time). When `false`, snaps to the nearest snap point by distance. (type `boolean`; default `false`; optional)
- `closeThreshold`: Close threshold as a fraction of the drawer size (0–1). (type `number`; default `0.25`; optional)
- `swipeDirection`: The swipe direction that dismisses the drawer. Defaults to the direction opposite the drawer's entry edge (`side`). (type `SwipeDirection`; optional)
- `fixed`: Whether fixed. (type `boolean`; optional)
- `dismissible`: Whether dismissible. (type `boolean`; default `true`; optional)
- `nested`: Whether nested. (type `boolean`; default `false`; optional)
- `side`: Direction. (type `Side`; default `'bottom'`; optional)
- `noBodyStyles`: When `true` the `body` doesn't get any styles assigned from the drawer (type `boolean`; optional)
- `handleOnly`: Whether handle only. (type `boolean`; default `false`; optional)
- `preventScrollRestoration`: Whether prevent scroll restoration. (type `boolean`; optional)
- `snapPoints`: Snap points used to position the drawer. Use numbers between 0 and 1 to represent fractions of the viewport height, numbers greater than 1 as pixel values, or strings in `px`/`rem` units. (type `DrawerSnapPoint[]`; optional)
#### Emits
Events for the DrawerRoot component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `drag`: Emitted while dragging with the live progress: 0 fully open, 1 closed. (type `[percentageDragged: number]`; parameters `percentageDragged: number`)
- `release`: Emitted when a drag gesture releases; `true` when the drawer stays open. (type `[open: boolean]`; parameters `open: boolean`)
- `close`: Emitted when close occurs. (type `[]`)
- `update:snapPoint`: Emitted when the snap point value changes. (type `[val: DrawerSnapPoint | null]`; parameters `val: DrawerSnapPoint | null`)
#### Slots
Slots for the DrawerRoot component.
- `default`: Custom content for the default slot. (type `((props: { open: boolean; close: () => void; }) => any) | undefined`)

### DrawerRootNested

- No documented props, emits, slots, or slot props were available.

### DrawerSwipeArea

#### Props
Properties for the DrawerSwipeArea component.
- `swipeDirection`: Override the swipe side that opens the drawer. Defaults to the opposite of the root swipe direction. (type `SwipeDirection`; optional)
- `disabled`: Disable swipe-to-open. (type `boolean`; default `false`; optional)

### DrawerTitle

- No documented props, emits, slots, or slot props were available.

### DrawerTrigger

#### Props
Properties for the DrawerTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DrawerTrigger component.
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### DrawerViewport

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`DrawerCompact` owns the handle/swipe-area/overlay/popup/header/content/footer composition and the drag/snap state flow (via `useDrawerSnapPoints` and `useSwipeDismiss`), while every primitive stays style-free and only the UI wrapper injects the `drawerVariants` classes. The popup transform is CSS-variable driven — the gesture layer writes variables, never inline transforms — so snap settling, release bounce and dismissal all resolve through CSS transitions. This mirrors the Base UI Drawer model. Ant Design, Element Plus, Mantine and Naive UI ship a single styled drawer; a dedicated draggable panel with `snapPoints` is typically a separate library (vaul, Base UI Drawer). SoybeanUI exposes per-slot `*Props`, a `size` scale, and the snap/indent/drag/swipe model inline.

| Capability               | SoybeanUI | shadcn/ui + vaul | reka-ui Drawer | Base UI | Ant Design | Element Plus | Mantine |
| :----------------------- | :-------: | :--------------: | :------------: | :-----: | :--------: | :----------: | :-----: |
| Reuses dialog primitives |    ✅     |        ✅        |       ✅       |   ✅    |     —      |      —       |    —    |
| Headless/styled split    |    ✅     |        ✅        |       ✅       |   ✅    |     —      |      —       |    —    |
| Drag-to-dismiss          |    ✅     |        ✅        |       ✅       |   ✅    |     —      |      —       |   ✅    |
| Snap points              |    ✅     |        ✅        |       ✅       |   ✅    |     —      |      —       |    —    |
| Swipe-to-open area       |    ✅     |        —         |       ✅       |   ✅    |     —      |      —       |    —    |
| Page indent effect       |    ✅     |        ✅        |       —        |   ✅    |     —      |      —       |    —    |
| Nested drawers           |    ✅     |        ✅        |       ✅       |   ✅    |     —      |      —       |    —    |
| Modality tiers           |    ✅     |        —         |       ✅       |   ✅    |     —      |      —       |    —    |
| Sizes (6)                |    ✅     |        —         |       —        |    —    |     —      |      —       |    —    |

`—` = unsupported or a different interaction model.

### Cautions

- `modal` defaults to `true`; the panel teleports to `document.body` and body scroll is locked by the hide-others layer. The `'trap-focus'` tier keeps outside pointer events alive but still traps focus.
- `side` picks the anchored edge. Vertical sides (`top`/`bottom`) cap the panel at `calc(100dvh - 2rem)` so a long body scrolls inside the `content` slot instead of growing past the viewport; horizontal sides fill the viewport height and cap their width.
- Drag-to-dismiss uses pointer capture; `dismissible` (default `true`) allows releasing past `closeThreshold` to close. Set `false` to force explicit actions. `swipeDirection` overrides the dismiss direction (defaults to the direction opposite the entry edge).
- Horizontal sides ship **vertical snap only** in this release — `snapPoints` resolves against the vertical axis, so `left`/`right` snap behaviour is not yet supported.
- `snapPoints` accepts fractions (0–1), pixel values (> 1) or CSS length strings; `snapPoint` tracks the current level and is bound with `v-model:snap-point`. The drawer opens at the first snap point and resets to it on close.
- The drag handle is rendered only for `side="bottom"` in `DrawerCompact`; compose `DrawerHandle` manually for other sides.
- `handleOnly` restricts dragging to the handle; `fixed` keeps the panel in place while inner content scrolls.
- `swipeable` renders a gesture strip at the drawer's edge; it is inert while the drawer is open.
- `nested` renders via `DrawerRootNested`; each nested drawer coordinates drag and release with its parent.
- Fullscreen defines the panel's size _and_ freezes its drag, matching how a dialog disables its draggable in fullscreen: a resting snap level below "fully open" would translate the panel back down and leave the half beyond its anchored edge off-screen, and a drag away from the edge would contradict the prop. Snapping and dragging resume when fullscreen is switched off; `snapPoints` stay configured throughout.
- Because the drag is suspended, dismissal in fullscreen falls back to the explicit paths: the close button, Escape, and an outside press on a non-modal drawer. A modal fullscreen drawer with `showClose={false}` and `dismissible={false}` therefore has no way out — keep the close button (or `modal={false}`) if the user must be able to leave it.
- The handle stops cycling snap levels while fullscreen, so it cannot rewrite `snapPoint` behind the scenes.
- The drawer renders **no** fullscreen button of its own, so the dialog's `showFullscreen` has no effect here — drive the state with `v-model:fullscreen`/`defaultFullscreen`, or render your own control inside the panel.
- An uncontrolled fullscreen session does not survive a close: the drawer reopens at `defaultFullscreen` (matching the dialog's reset).

### Migrating from `BottomSheet`

v0.50.0 renamed the whole family — the name `bottom-sheet` is retired.

| Before                                                                                 | After                                                              |
| :------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
| `SBottomSheet`                                                                         | `SDrawer`                                                          |
| `BottomSheetRoot` / `BottomSheetRootNested`                                            | `DrawerRoot` / `DrawerRootNested`                                  |
| `BottomSheetPopup` / `BottomSheetOverlay`                                              | `DrawerPopup` / `DrawerOverlay`                                    |
| `BottomSheetHandle` / `BottomSheetCompact`                                             | `DrawerHandle` / `DrawerCompact`                                   |
| `BottomSheetTitle` / `BottomSheetDescription`                                          | `DrawerTitle` / `DrawerDescription`                                |
| `BottomSheetHeader` / `BottomSheetContent` / `BottomSheetFooter`                       | `DrawerHeader` / `DrawerContent` / `DrawerFooter`                  |
| `BottomSheetTrigger` / `BottomSheetClose` / `BottomSheetCancel` / `BottomSheetConfirm` | `DrawerTrigger` / `DrawerClose` / `DrawerCancel` / `DrawerConfirm` |
| `v-model:active-snap-point`                                                            | `v-model:snap-point`                                               |
| `direction` prop (headless)                                                            | `side` prop                                                        |
| `@soybeanjs/headless/bottom-sheet`                                                     | `@soybeanjs/headless/drawer`                                       |
| `data-soybean-bottom-sheet-*`, `soybean-bottom-sheet-dragging`                         | `data-soybean-drawer-*`, `soybean-drawer-dragging`                 |
| `data-soybean-bottom-sheet-scale`                                                      | removed with the scale-background engine (see below)               |

The old `SDrawer` (a dialog with a side) was renamed to `SSheet`. See [Sheet](/components/sheet) for the side-panel API.

### Migrating from the vaul-style engine

v0.50.0 replaced the vaul-derived engine with a Base UI-style one. The public surface changes:

| Before                                                | After                                                                                       |
| :---------------------------------------------------- | :------------------------------------------------------------------------------------------ |
| `shouldScaleBackground` / `setBackgroundColorOnScale` | removed. Wrap the page in `DrawerIndent` + `DrawerIndentBackground` inside `DrawerRoot`     |
| `fadeFromIndex`                                       | removed; the overlay fades continuously with the swipe progress                             |
| `snapPoint` defaulting to `null`                      | defaults to the first entry of `snapPoints` (the drawer opens positioned at a snap point)   |
| implicit drag direction from `side`                   | still the default, overridable with `swipeDirection`                                        |
| imperative transforms                                 | CSS variables (`--soybean-drawer-snap-point-offset`, `--soybean-drawer-swipe-movement-x/y`) |

```vue

  <div data-soybean-drawer-scale>Page</div>

  <DrawerIndent class="page-indent">Page</DrawerIndent>
  <template #trigger><SButton>Open</SButton></template>

```

```vue

  <template #trigger><SButton>Open</SButton></template>
  Content

  <template #trigger><SButton>Open</SButton></template>
  Content

```

### Roadmap

Horizontal snap points, on-device verification of the touch pipeline (iOS Safari / Android Chrome), and iOS virtual keyboard coordination.

## FAQ

### How do I anchor the drawer to a different edge?

Set `side` to `top`/`bottom`/`left`/`right`:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

### How do I enable snap points?

Pass an array of fractions, pixels or CSS lengths, and bind the active level:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

### How do I open the drawer with a swipe gesture?

Set `swipeable`. An edge strip is rendered at the panel's `side` and swipes in the opposite direction:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

### How do I disable drag-to-dismiss?

Set `dismissible={false}` to require an explicit action:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

### How do I restrict dragging to the handle?

Set `handle-only`:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

### How do I build a non-modal side panel that still traps focus?

Use the `'trap-focus'` tier:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

### How do I make the drawer fullscreen?

Bind `v-model:fullscreen`, or let it start fullscreen with `default-fullscreen`. The panel grows to the viewport from its `side` edge and stops responding to drags, so snapping and dragging resume only once you switch fullscreen off:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <div>Drawer content</div>

```

## DropdownMenu

- Page URL: /components/dropdown-menu
- Markdown URL: /components/dropdown-menu.md
- Description: Displays a menu to the user—such as a set of actions or functions—triggered by a button. SDropdownMenu is a data-driven menu built on the headless menu primitives (MenuOptions/MenuItem/…), rendered through the shared popover portal. The family also ships checkbox (SDropdownMenuCheckbox, multi-select), radio (SDropdownMenuRadio, single-select) and custom (SDropdownMenuWrapper) variants.

# DropdownMenu

## Overview

Displays a menu to the user—such as a set of actions or functions—triggered by a button. `SDropdownMenu` is a data-driven menu built on the headless menu primitives (`MenuOptions`/`MenuItem`/…), rendered through the shared popover portal. The family also ships checkbox (`SDropdownMenuCheckbox`, multi-select), radio (`SDropdownMenuRadio`, single-select) and custom (`SDropdownMenuWrapper`) variants.

Use a dropdown for a compact action menu. For navigation menus use `nav-menu`; for a rich hover preview use `hover-card`.

## Usage

Usage examples for dropdown-menu are rendered on the site.

## Features

- 🧩 Headless/menu based — built on the shared menu primitives with full keyboard navigation (arrow/Home/End/PageUp/PageDown), typeahead and roving focus
- 🖱️ Trigger modes — `trigger="click"` or `"hover"`; `delayDuration`/`skipDelayDuration` tune hover latency
- 📊 Data-driven — pass `items` (with `value`/`label`/`icon`/`disabled`/`hidden`/`separator`…) or use the item slots
- ☑️ Checkbox variant — `SDropdownMenuCheckbox` for multi-select with `v-model`
- 🔘 Radio variant — `SDropdownMenuRadio` for single-select with `v-model`
- 🧩 Wrapper variant — `SDropdownMenuWrapper` for fully custom menu content
- 🎯 Placement — popper `placement` + `showArrow`
- 🎭 Modal — `modal` controls outside-pointer blocking and focus trapping
- 🪜 Submenus — nested submenu support with side-aware open/close keys (RTL-aware)
- 🙈 Hidden items — an item flagged `hidden` (and its whole subtree) is dropped from the menu
- ♿ Accessible — `role="menu"`/`menuitem`, `aria-checked` on checkbox/radio, `axe-core` clean

## Component family

- `SDropdownMenu` (styled) — the data-driven menu; forwards to `DropdownMenuCompact`
- `SDropdownMenuCheckbox` (styled) — multi-select menu with `v-model`
- `SDropdownMenuRadio` (styled) — single-select menu with `v-model`
- `SDropdownMenuWrapper` (styled) — custom-content menu
- `DropdownMenuCompact` / `DropdownMenuWrapperCompact` / `DropdownMenuCheckboxCompact` / `DropdownMenuRadioCompact` (headless) — the aggregated composites
- `MenuOptions`/`MenuItem`/… (headless) — the shared menu primitives (roving focus, keyboard nav, submenus)

## Demos

Interactive demos for dropdown-menu are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (26): DropdownMenu, DropdownMenuAnchor, DropdownMenuArrow, DropdownMenuCheckbox, DropdownMenuCheckboxCompact, DropdownMenuCheckboxGroup, DropdownMenuCheckboxItem, DropdownMenuCompact, DropdownMenuContent, DropdownMenuGroup, DropdownMenuGroupLabel, DropdownMenuItem, DropdownMenuItemIndicator, DropdownMenuPortal, DropdownMenuRadio, DropdownMenuRadioCompact, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuRoot, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, DropdownMenuWrapper, DropdownMenuWrapperCompact.

### DropdownMenu

#### Props
Properties for the DropdownMenu component.
- `class`: class of menu popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DropdownMenuUi>`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `DropdownMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `DropdownMenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `DropdownMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `DropdownMenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `DropdownMenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `DropdownMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `DropdownMenuSubContentProps`; optional)
#### Emits
Events for the DropdownMenu component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the DropdownMenu component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### DropdownMenuAnchor

- No documented props, emits, slots, or slot props were available.

### DropdownMenuArrow

- No documented props, emits, slots, or slot props were available.

### DropdownMenuCheckbox

#### Props
Properties for the DropdownMenuCheckbox component.
- `class`: class of menu popup (type `((string | false | Record<string, any> | ClassValue[]) & (string | false | Record<string, any> | import("vue").ClassV...`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DropdownMenuUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuCheckboxOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `DropdownMenuGroupLabelProps`; optional)
- `checkboxItemProps`: Properties forwarded to the checkbox item element. (type `DropdownMenuCheckboxItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `DropdownMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `DropdownMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DropdownMenuCheckbox component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)
- `select`: Emitted when select occurs. (type `[item: MenuCheckboxOptionData<T>, event: Event]`; parameters `item: MenuCheckboxOptionData<T>, event: Event`)
#### Slots
Slots for the DropdownMenuCheckbox component.
- `item`: Custom content for the item slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### DropdownMenuCheckboxCompact

#### Props
Properties for the DropdownMenuCheckboxCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuCheckboxOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `DropdownMenuGroupLabelProps`; optional)
- `checkboxItemProps`: Properties forwarded to the checkbox item element. (type `DropdownMenuCheckboxItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `DropdownMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `DropdownMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DropdownMenuCheckboxCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)
- `select`: Emitted when select occurs. (type `[item: MenuCheckboxOptionData<T>, event: Event]`; parameters `item: MenuCheckboxOptionData<T>, event: Event`)
#### Slots
Slots for the DropdownMenuCheckboxCompact component.
- `item`: Custom content for the item slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### DropdownMenuCheckboxGroup

- No documented props, emits, slots, or slot props were available.

### DropdownMenuCheckboxItem

- No documented props, emits, slots, or slot props were available.

### DropdownMenuCompact

#### Props
Properties for the DropdownMenuCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `DropdownMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `DropdownMenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `DropdownMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `DropdownMenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `DropdownMenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `DropdownMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `DropdownMenuSubContentProps`; optional)
#### Emits
Events for the DropdownMenuCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the DropdownMenuCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### DropdownMenuContent

#### Props
Properties for the DropdownMenuContent component.
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
#### Emits
Events for the DropdownMenuContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### DropdownMenuGroup

- No documented props, emits, slots, or slot props were available.

### DropdownMenuGroupLabel

- No documented props, emits, slots, or slot props were available.

### DropdownMenuItem

- No documented props, emits, slots, or slot props were available.

### DropdownMenuItemIndicator

- No documented props, emits, slots, or slot props were available.

### DropdownMenuPortal

- No documented props, emits, slots, or slot props were available.

### DropdownMenuRadio

#### Props
Properties for the DropdownMenuRadio component.
- `class`: class of menu popup (type `((string | false | Record<string, any> | ClassValue[]) & (string | false | Record<string, any> | import("vue").ClassV...`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DropdownMenuUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuRadioOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `DropdownMenuGroupLabelProps`; optional)
- `radioItemProps`: Properties forwarded to the radio item element. (type `DropdownMenuRadioItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `DropdownMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `DropdownMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DropdownMenuRadio component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: Exclude<T, undefined> | null]`; parameters `payload: Exclude<T, undefined> | null`)
- `select`: Emitted when select occurs. (type `[item: MenuRadioOptionData<T>, event: Event]`; parameters `item: MenuRadioOptionData<T>, event: Event`)
#### Slots
Slots for the DropdownMenuRadio component.
- `item`: Custom content for the item slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### DropdownMenuRadioCompact

#### Props
Properties for the DropdownMenuRadioCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
- `items`: Items rendered by the component. (type `MenuRadioOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `DropdownMenuGroupLabelProps`; optional)
- `radioItemProps`: Properties forwarded to the radio item element. (type `DropdownMenuRadioItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `DropdownMenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `DropdownMenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the DropdownMenuRadioCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: Exclude<T, undefined> | null]`; parameters `payload: Exclude<T, undefined> | null`)
- `select`: Emitted when select occurs. (type `[item: MenuRadioOptionData<T>, event: Event]`; parameters `item: MenuRadioOptionData<T>, event: Event`)
#### Slots
Slots for the DropdownMenuRadioCompact component.
- `item`: Custom content for the item slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `() => any`)

### DropdownMenuRadioGroup

- No documented props, emits, slots, or slot props were available.

### DropdownMenuRadioItem

- No documented props, emits, slots, or slot props were available.

### DropdownMenuRoot

#### Props
Properties for the DropdownMenuRoot component.
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the DropdownMenuRoot component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### DropdownMenuSeparator

- No documented props, emits, slots, or slot props were available.

### DropdownMenuSub

- No documented props, emits, slots, or slot props were available.

### DropdownMenuSubContent

- No documented props, emits, slots, or slot props were available.

### DropdownMenuSubTrigger

- No documented props, emits, slots, or slot props were available.

### DropdownMenuTrigger

#### Props
Properties for the DropdownMenuTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### DropdownMenuWrapper

#### Props
Properties for the DropdownMenuWrapper component.
- `class`: class of menu popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DropdownMenuUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the DropdownMenuWrapper component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### DropdownMenuWrapperCompact

#### Props
Properties for the DropdownMenuWrapperCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DropdownMenuTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DropdownMenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DropdownMenuContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DropdownMenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `DropdownMenuArrowProps`; optional)
- `trigger`: The trigger type of the dropdown menu. - `click`: The dropdown menu will be opened when the trigger is clicked. - `hover`: The dropdown menu will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the dropdown menu gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the DropdownMenuWrapperCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

## Notes

### Architecture and benchmark differences

The dropdown-menu family composes the shared `menu` primitives (`MenuOptions`/`MenuItem`) inside a popover portal; the UI wrappers only inject the shared `menuVariants` classes (via `provideMenuUi`) and forward props/slots. This mirrors radix-ui/shadcn-ui's headless menu split. Ant Design, Element Plus, Mantine and Naive UI ship a single styled dropdown with `items`/`onSelect` props; SoybeanUI additionally exposes dedicated checkbox/radio/wrapper variants, a `size` scale, and full keyboard/typeahead behavior through the shared menu layer.

| Capability            | SoybeanUI | shadcn/ui | Ant Design Dropdown | Element Plus Dropdown | Mantine Menu | Naive UI Dropdown |
| :-------------------- | :-------: | :-------: | :-----------------: | :-------------------: | :----------: | :---------------: |
| Headless/styled split |    ✅     |    ✅     |          —          |           —           |      —       |         —         |
| Data-driven items     |    ✅     |    ✅     |         ✅          |          ✅           |      ✅      |        ✅         |
| Checkbox / radio      |    ✅     |    ✅     |          —          |           —           |      ✅      |         —         |
| Trigger click/hover   |    ✅     |    ✅     |         ✅          |          ✅           |      ✅      |        ✅         |
| Keyboard + typeahead  |    ✅     |    ✅     |          —          |           —           |      —       |         —         |
| Submenu               |    ✅     |    ✅     |         ✅          |          ✅           |      ✅      |        ✅         |
| Sizes (6)             |    ✅     |     —     |          —          |           —           |      —       |         —         |

`—` = unsupported or a different interaction model.

### Cautions

- `SDropdownMenu` is `modal` by default (`true`); pass `modal={false}` for a lightweight, non-blocking menu.
- `trigger` accepts `"click"` (default) or `"hover"`; for hover, tune `delayDuration` (open) and `skipDelayDuration` (between triggers).
- `items` is data-driven; use the matching item slots (`item`, `item-leading`, `item-trailing`) for custom rendering.
- Checkbox/radio variants bind selection with `v-model`; radio expects a single value, checkbox an array.
- The menu is rendered through a portal; position it inside a relatively-positioned ancestor only with `portalProps: { disabled: true }`.

### Roadmap

N/A — dropdown-menu is feature-complete for the current parity set.

## FAQ

### How do I build a basic action menu?

Pass `items` and a `trigger` slot:

```vue

  <template #trigger><SButton>Actions</SButton></template>

```

### How do I use the checkbox (multi-select) variant?

Use `SDropdownMenuCheckbox` with `v-model`:

```vue

  <template #trigger><SButton>Filters</SButton></template>

```

### How do I use the radio (single-select) variant?

Use `SDropdownMenuRadio` with `v-model`:

```vue

  <template #trigger><SButton>Sort</SButton></template>

```

### How do I build a fully custom menu?

Use `SDropdownMenuWrapper` and fill the default slot with `MenuItem`s:

```vue

  <template #trigger><SButton>Open</SButton></template>
  <MenuItem value="a">Item A</MenuItem>
  <MenuItem value="b">Item B</MenuItem>

```

### How do I open on hover?

Set `trigger="hover"` and adjust the delays:

```vue

  <template #trigger><SButton>Hover</SButton></template>

```

## Editable

- Page URL: /components/editable
- Markdown URL: /components/editable.md
- Description: An inline text editor that switches between preview and edit states. In preview mode the value is shown as a focusable text node (or a placeholder); focusing, double-clicking, or clicking the edit button enters edit mode, then submitting (Enter/blur/submit trigger) or cancelling (Esc/cancel trigger) returns to preview. The structure follows the headless core + styled wrapper split: the 8 EditableRoot-family components in @soybeanjs/headless (zero styles) own the full state machine, and SEditable injects the editableVariants styles (8 slots: root/area/preview/input/controls/editTrigger/submitTrigger/cancelTrigger).

# Editable

## Overview

An inline text editor that switches between preview and edit states. In preview mode the value is shown as a focusable text node (or a placeholder); focusing, double-clicking, or clicking the edit button enters edit mode, then submitting (Enter/blur/submit trigger) or cancelling (Esc/cancel trigger) returns to preview. The structure follows the headless core + styled wrapper split: the 8 `EditableRoot`-family components in `@soybeanjs/headless` (zero styles) own the full state machine, and `SEditable` injects the `editableVariants` styles (8 slots: root/area/preview/input/controls/editTrigger/submitTrigger/cancelTrigger).

## Usage

Usage examples for editable are rendered on the site.

## Features

- 🔀 Two-state machine — preview/edit switching with `update:state` reporting `edit` / `submit` / `cancel`
- 🖱️ Activation modes — `activationMode`: `focus` (focus to edit, default), `dblclick` (double-click to edit), `none` (edit only via the edit trigger or `edit()`)
- ⌨️ Submit modes — `submitMode`: `blur` (submit on blur, default), `enter` (submit on Enter), `both`, `none` (blur cancels only); Esc always cancels
- 🔁 Controlled/uncontrolled — `modelValue` + `update:modelValue` for controlled, `defaultValue` for uncontrolled; the `submit` event carries the submitted value
- 🎛️ Editing UX — `selectOnFocus` (select all on focus), `startWithEditMode` (enter edit on mount), `maxLength`, `autoResize` (inline-grid width)
- 🧩 Headless/styled split — `EditableCompact` aggregates the 8 primitives and exposes 6 `*Props` channels (area/preview/input/editTrigger/submitTrigger/cancelTrigger)
- ♿ Accessible by default — focusable preview (`tabindex="0"`), full keyboard support (Enter submits / Esc cancels), localized trigger `aria-label`s, and a hidden input proxy (`VisuallyHiddenInput`) for forms
- 🎨 8-slot styling — root/area/preview/input/controls/editTrigger/submitTrigger/cancelTrigger plus `size` variants (xs–2xl)

## Component family

- `SEditable` (styled) — the entry wrapper; pure `defineProps` + `editableVariants` with dynamic 8-slot forwarding and `useForwardListeners` event merging
- `EditableRoot` (headless) — the state-machine owner: holds `modelValue`/`inputValue`/`isEditing`/`placeholder`/`isEmpty`, exposes `edit`/`cancel`/`submit`; renders `data-dismissable-layer` for blur/outside-click handling; inside a `.form` container with a `name` it renders the hidden input proxy
- `EditableArea` (headless) — the container; uses an inline-grid layout when `autoResize` is on
- `EditablePreview` (headless) — the preview text; `tabindex = disabled ? -1 : 0`, activated on focusin/dblclick
- `EditableInput` (headless) — the real input; activate/cancel/submit keyboard handling and `selectOnFocus` selection
- `EditableEditTrigger` / `EditableSubmitTrigger` / `EditableCancelTrigger` (headless) — `Button`-based triggers; `aria-label` falls back to `useLocaleMessages` localized messages; disabled when `disabled || readonly`
- `EditableCompact` (headless) — the aggregated composite of root/area/preview/input and the three triggers; slot props provide `modelValue`/`inputValue`/`isEditing`/`isEmpty`/`edit`/`cancel`/`submit`

## Demos

Interactive demos for editable are rendered on the site.

- 01 Basic — controlled `v-model` + placeholder with `submit` / `update:state` events
- 02 Size — `size` variants
- 03 Disabled — `disabled`
- 04 Activation mode — `focus` vs `dblclick`
- 05 Custom styling — 8-slot `ui` overrides

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (9): Editable, EditableArea, EditableCancelTrigger, EditableCompact, EditableEditTrigger, EditableInput, EditablePreview, EditableRoot, EditableSubmitTrigger.

### Editable

#### Props
Properties for the Editable component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<EditableUi>`; optional)
- `areaProps`: Properties forwarded to the area element. (type `EditableAreaProps`; optional)
- `previewProps`: Properties forwarded to the preview element. (type `EditablePreviewProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `EditableInputProps`; optional)
- `editTriggerProps`: Properties forwarded to the edit trigger element. (type `EditableEditTriggerProps`; optional)
- `submitTriggerProps`: Properties forwarded to the submit trigger element. (type `EditableSubmitTriggerProps`; optional)
- `cancelTriggerProps`: Properties forwarded to the cancel trigger element. (type `EditableCancelTriggerProps`; optional)
- `defaultValue`: The default value of the editable field. (type `string`; optional)
- `modelValue`: The controlled value of the editable field. (type `string`; optional)
- `placeholder`: The placeholder for the editable field. (type `string | EditablePlaceholder`; optional)
- `dir`: The reading direction of the editable field when applicable. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with the editable field. (type `boolean`; optional)
- `readonly`: When `true`, prevents the user from editing the value. (type `boolean`; optional)
- `activationMode`: The activation event of the editable field. (type `EditableActivationMode`; optional)
- `selectOnFocus`: Whether to select the text in the input when it is focused. (type `boolean`; optional)
- `submitMode`: The submit event of the editable field. (type `EditableSubmitMode`; optional)
- `startWithEditMode`: Whether to start with the edit mode active. (type `boolean`; optional)
- `maxLength`: The maximum number of characters allowed. (type `number`; optional)
- `autoResize`: Whether the editable field should auto resize. (type `boolean`; optional)
- `id`: The id of the field. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Editable component.
- `update:modelValue`: Event handler called whenever the model value changes. (type `[value: string]`; parameters `value: string`)
- `submit`: Event handler called when a value is submitted. (type `[value: string]`; parameters `value: string`)
- `update:state`: Event handler called when the editable field changes state. (type `[state: EditableEventState]`; parameters `state: EditableEventState`)
#### Slots
Slot properties for the Editable component.
- `default`: Custom content for the default slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `preview`: Custom content for the preview slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `input`: Custom content for the input slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `edit-trigger`: Custom content for the edit trigger slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `submit-trigger`: Custom content for the submit trigger slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `cancel-trigger`: Custom content for the cancel trigger slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)

### EditableArea

#### Props
Properties for the EditableArea component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### EditableCancelTrigger

#### Props
Properties for the EditableCancelTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### EditableCompact

#### Props
Properties for the EditableCompact component.
- `areaProps`: Properties forwarded to the area element. (type `EditableAreaProps`; optional)
- `previewProps`: Properties forwarded to the preview element. (type `EditablePreviewProps`; optional)
- `inputProps`: Properties forwarded to the input element. (type `EditableInputProps`; optional)
- `editTriggerProps`: Properties forwarded to the edit trigger element. (type `EditableEditTriggerProps`; optional)
- `submitTriggerProps`: Properties forwarded to the submit trigger element. (type `EditableSubmitTriggerProps`; optional)
- `cancelTriggerProps`: Properties forwarded to the cancel trigger element. (type `EditableCancelTriggerProps`; optional)
- `defaultValue`: The default value of the editable field. (type `string`; optional)
- `modelValue`: The controlled value of the editable field. (type `string`; optional)
- `placeholder`: The placeholder for the editable field. (type `string | EditablePlaceholder`; optional)
- `dir`: The reading direction of the editable field when applicable. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with the editable field. (type `boolean`; optional)
- `readonly`: When `true`, prevents the user from editing the value. (type `boolean`; optional)
- `activationMode`: The activation event of the editable field. (type `EditableActivationMode`; optional)
- `selectOnFocus`: Whether to select the text in the input when it is focused. (type `boolean`; optional)
- `submitMode`: The submit event of the editable field. (type `EditableSubmitMode`; optional)
- `startWithEditMode`: Whether to start with the edit mode active. (type `boolean`; optional)
- `maxLength`: The maximum number of characters allowed. (type `number`; optional)
- `autoResize`: Whether the editable field should auto resize. (type `boolean`; optional)
- `id`: The id of the field. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the EditableCompact component.
- `update:modelValue`: Event handler called whenever the model value changes. (type `[value: string]`; parameters `value: string`)
- `submit`: Event handler called when a value is submitted. (type `[value: string]`; parameters `value: string`)
- `update:state`: Event handler called when the editable field changes state. (type `[state: EditableEventState]`; parameters `state: EditableEventState`)
#### Slots
Slots for the EditableCompact component.
- `default`: Custom content for the default slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `preview`: Custom content for the preview slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `input`: Custom content for the input slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `edit-trigger`: Custom content for the edit trigger slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `submit-trigger`: Custom content for the submit trigger slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
- `cancel-trigger`: Custom content for the cancel trigger slot. (type `((props: EditableCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the EditableCompact component.
- `modelValue`: Current model value. (type `string | undefined`; required)
- `inputValue`: Input value exposed in the slot scope. (type `string`; required)
- `isEditing`: Whether an editing. (type `boolean`; required)
- `isEmpty`: Whether an empty. (type `boolean`; required)
- `edit`: Edit exposed in the slot scope. (type `() => void`; required)
- `cancel`: Whether the component can cel. (type `() => void`; required)
- `submit`: Submit exposed in the slot scope. (type `() => void`; required)

### EditableEditTrigger

#### Props
Properties for the EditableEditTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### EditableInput

#### Props
Properties for the EditableInput component.
- `id`: Id. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### EditablePreview

#### Props
Properties for the EditablePreview component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### EditableRoot

#### Props
Properties for the EditableRoot component.
- `defaultValue`: The default value of the editable field. (type `string`; optional)
- `modelValue`: The controlled value of the editable field. (type `string`; optional)
- `placeholder`: The placeholder for the editable field. (type `string | EditablePlaceholder`; optional)
- `dir`: The reading direction of the editable field when applicable. (type `Direction`; optional)
- `disabled`: When `true`, prevents the user from interacting with the editable field. (type `boolean`; optional)
- `readonly`: When `true`, prevents the user from editing the value. (type `boolean`; optional)
- `activationMode`: The activation event of the editable field. (type `EditableActivationMode`; optional)
- `selectOnFocus`: Whether to select the text in the input when it is focused. (type `boolean`; optional)
- `submitMode`: The submit event of the editable field. (type `EditableSubmitMode`; optional)
- `startWithEditMode`: Whether to start with the edit mode active. (type `boolean`; optional)
- `maxLength`: The maximum number of characters allowed. (type `number`; optional)
- `autoResize`: Whether the editable field should auto resize. (type `boolean`; optional)
- `id`: The id of the field. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the EditableRoot component.
- `update:modelValue`: Event handler called whenever the model value changes. (type `[value: string]`; parameters `value: string`)
- `submit`: Event handler called when a value is submitted. (type `[value: string]`; parameters `value: string`)
- `update:state`: Event handler called when the editable field changes state. (type `[state: EditableEventState]`; parameters `state: EditableEventState`)

### EditableSubmitTrigger

#### Props
Properties for the EditableSubmitTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`EditableRoot` uses `useControllableState` to unify controlled/uncontrolled; `inputValue` (the edit buffer) is separate from `modelValue` (the committed value), and `currentValue` picks one based on the state. While editing, an external `modelValue` push does not overwrite the in-progress input (it is written back only on submit/cancel), so a controlled parent cannot stomp the user's typing. Activation (focus/dblclick/edit trigger) and submission (blur/enter/submit trigger) are decoupled both ways; `useFocusOutside`/`usePointerdownOutside` gate on `isEditing` to implement submit-on-blur. `autoResize` uses an inline-grid + `grid-template-columns: auto` layout so the input hugs its content. The API is co-designed with reka-ui's `Editable` (activation/submit modes, `selectOnFocus`, `startWithEditMode`, and the form proxy are all present); Ant Design's `Typography` editable only offers button activation plus a controlled `editing` flag; Element Plus and shadcn/ui have no equivalent component; Mantine's `EditableText` covers a subset of the activation/submit behavior.

| Capability                              | SoybeanUI | reka-ui | Ant Design Typography | Mantine EditableText | Element Plus | shadcn/ui |
| :-------------------------------------- | :-------: | :-----: | :-------------------: | :------------------: | :----------: | :-------: |
| headless/styled split                   |    ✅     |   ✅    |           —           |          —           |      —       |     —     |
| Activation mode (focus/dblclick/none)   |    ✅     |   ✅    |           —           |          ⚠️          |      —       |     —     |
| Submit mode (blur/enter/none/both)      |    ✅     |   ✅    |           —           |          ⚠️          |      —       |     —     |
| Esc to cancel                           |    ✅     |   ✅    |          ⚠️           |          ✅          |      —       |     —     |
| `selectOnFocus`                         |    ✅     |   ✅    |           —           |          ✅          |      —       |     —     |
| `startWithEditMode`                     |    ✅     |   ✅    |          ⚠️           |          ✅          |      —       |     —     |
| `autoResize` (width fits content)       |    ✅     |   ✅    |           —           |          —           |      —       |     —     |
| Form proxy (`name` + form hidden input) |    ✅     |   ✅    |           —           |          —           |      —       |     —     |
| Localized trigger `aria-label`          |    ✅     |   ⚠️    |           —           |          —           |      —       |     —     |
| Controlled/uncontrolled + submit event  |    ✅     |   ✅    |          ✅           |          ✅          |      —       |     —     |

`⚠️` = partial (Mantine covers activation/submit subsets via `activateOnFocus`/`submitOnBlur`; AntD covers `startWithEditMode`-like behavior through the controlled `editing` flag; reka-ui hardcodes the trigger `aria-label`, while SoybeanUI localizes it with `useLocaleMessages`).

### Cautions

- An external controlled update does not overwrite in-progress input: while editing, `modelValue` pushes are not written into the edit buffer — the input is written back on submit/cancel, avoiding "typing being stomped"; outside edit mode the value stays synced.
- Blur submission depends on focus leaving the component root: `useFocusOutside` listens on the document `focusin` event, so `submitMode` logic runs only when focus moves outside; with `submitMode: 'none'` blur just cancels.
- Form integration: the `VisuallyHiddenInput` proxy renders only when the component sits in a container with the `.form` class (`isFormControl`) and a `name` is provided; otherwise no hidden input is emitted.
- `placeholder` accepts a string or an `{ edit, preview }` object — separate texts for edit and preview states.
- `readonly` and `disabled` differ: `readonly` blocks entering edit (`edit()` guard + disabled triggers + readonly input) without touching the value; `disabled` additionally disables preview focus and the hidden proxy.
- A custom `preview` slot has no default `tabindex` — provide a focusable element or activate via `EditableEditTrigger`.
- With `activationMode: 'none'`, focus does not enter edit — activate only via the edit trigger or the exposed `edit()` (`defineExpose`).
- In controlled usage, listen to `submit` for the final committed value (Enter/blur/submit trigger all follow the same path); `update:modelValue` fires at the same time.

## FAQ

### How do I edit on double-click instead of focus?

Set `activationMode="dblclick"`:

```vue

```

### How do I cancel on blur instead of submitting?

Set `submitMode="none"` — blur runs `cancel()` (no `submit`/`update:modelValue`), Esc still cancels, and Enter still submits:

```vue

```

### How do I trigger editing with a button?

Use `EditableEditTrigger` (available in the headless composite), or call the exposed method via a ref:

```vue

<button @click="editableRef?.edit()">Edit</button>
```

### How do I get the value after submitting?

Listen to the `submit` event (it fires together with `update:modelValue`):

```vue

```

```ts
function onSubmit(value: string) {
  // the committed value
}
```

### How do I make the input resize to its content?

Enable `autoResize` — the input container uses an inline-grid layout and follows the content width:

```vue

```

### How do I submit along with a native form?

Place the component inside a form container with the `.form` class and pass a `name`; the component renders a hidden input proxy that submits with the form:

```vue
<form class="form" @submit.prevent>
  <SEditable name="nickname" default-value="Nickname" />
  <button type="submit">Submit</button>
</form>
```

### How do I select all text when editing starts?

Set `selectOnFocus` — entering edit focuses the input and selects the existing content for direct overwrite:

```vue

```

## Empty

- Page URL: /components/empty
- Markdown URL: /components/empty.md
- Description: A lightweight empty-state component that highlights missing content and guides the user toward a next action. SEmpty is a UI-only composition of plain elements plus the SIcon component, styled by the emptyVariants style recipe (6 slots, 6 sizes).

# Empty

## Overview

A lightweight empty-state component that highlights missing content and guides the user toward a next action. `SEmpty` is a **UI-only** component: it renders plain elements for the root/header/media/title/description/content anatomy plus `SIcon` for the default media, all styled by the `emptyVariants` recipe (6 slots, 6 sizes).

Use it for "no results", empty inboxes, blank tables, or onboarding prompts. Prefer `alert` for inline feedback about state, and `skeleton` when content is still loading rather than absent.

There is no headless `empty` family: an empty state carries no keyboard, focus, ARIA or state logic that would need to be shared across wrappers, so the whole assembly lives in the UI layer and keeps `data-soybean-empty-*` attributes for styling and tests.

## Usage

Usage examples for empty are rendered on the site.

## Features

- 🧩 UI-only anatomy shell — `SEmpty` owns the header/media/title/description orchestration and stays style-driven; there is no headless `empty` family to compose
- 🖼️ Media / icon — `icon` prop or the `media` slot for an illustration, emoji or custom graphic
- 🏷️ Title + description — `title`/`description` props or the matching slots
- ⚡ Action area — `content`/`default` slots for buttons or follow-up guidance
- 🎨 6 sizes — xs–2xl `size` matching `ThemeSize`
- 🎛️ Per-slot control — `headerProps`/`mediaProps`/`contentProps`/`titleProps`/`descriptionProps` forwarded to each part
- ♿ Accessible by default — title renders as a real heading and `axe-core` reports zero violations

## Component family

`SEmpty` is a single export. It renders the whole anatomy itself and exposes `data-soybean-empty-root` / `-header` / `-media` / `-title` / `-description` / `-content` on the matching nodes, so `class`/`ui` and per-part `*Props` reach every part.

## Demos

Interactive demos for empty are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyRoot, EmptyTitle.

### Empty

#### Props
Properties for the Empty component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<EmptyUi>`; optional)
- `size`: Size variant of the component. (type `ThemeSize`; optional)
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `icon`: Icon rendered by the component. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)
- `headerProps`: Properties forwarded to the header element. (type `EmptyHeaderProps`; optional)
- `mediaProps`: Properties forwarded to the media element. (type `EmptyMediaProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `EmptyContentProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `EmptyTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `EmptyDescriptionProps`; optional)
#### Slots
Slots for the Empty component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `media`: Custom content for the media slot. (type `(() => any) | undefined`)
- `title`: Custom content for the title slot. (type `(() => any) | undefined`)
- `description`: Custom content for the description slot. (type `(() => any) | undefined`)
- `content`: Custom content for the content slot. (type `(() => any) | undefined`)

### EmptyContent

- No documented props, emits, slots, or slot props were available.

### EmptyDescription

- No documented props, emits, slots, or slot props were available.

### EmptyHeader

- No documented props, emits, slots, or slot props were available.

### EmptyMedia

- No documented props, emits, slots, or slot props were available.

### EmptyRoot

- No documented props, emits, slots, or slot props were available.

### EmptyTitle

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`SEmpty` owns the header/media/title/description orchestration in the UI layer — the empty state is an anatomy shell with no behavior behind it, so it deliberately has no headless family. This mirrors shadcn/ui's composition-first approach, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled `Empty` with `image`/`description` props. SoybeanUI exposes a full per-part `*Props` channel set and a `size` scale the single-package libraries generally omit, and renders the default media through `SIcon`.

| Capability            | SoybeanUI | shadcn/ui | Ant Design Empty | Element Plus Empty | Mantine | Naive UI Empty |
| :-------------------- | :-------: | :-------: | :--------------: | :----------------: | :-----: | :------------: |
| Headless/styled split |    ✅     |    ✅     |        —         |         —          |    —    |       —        |
| Media / icon          |    ✅     |    ✅     |        ✅        |         ✅         |   ✅    |       ✅       |
| Title                 |    ✅     |     —     |        ✅        |         ✅         |   ✅    |       ✅       |
| Description           |    ✅     |     —     |        ✅        |         ✅         |   ✅    |       ✅       |
| Action / content slot |    ✅     |     —     |        ✅        |         ✅         |   ✅    |       ✅       |
| Size variants (6)     |    ✅     |     —     |        —         |         —          |    —    |       —        |
| Per-part `*Props`     |    ✅     |    ✅     |        —         |         —          |    —    |       —        |

`—` = unsupported or a different interaction model.

### Cautions

- The default media renders through `SIcon`, so any Iconify name or component works out of the box. Provide the `media` slot for an illustration or emoji instead.
- The title renders as a heading; keep the empty state at an appropriate heading level for the surrounding document outline.
- The root uses a dashed border by default — override via `class`/`ui` when embedding inside a card or a filled surface.
- `Empty` is purely presentational and holds no state; it does not intercept focus or provide interactive semantics.

### Roadmap

No blocking gaps identified for the core empty API.

## FAQ

### How do I show an icon or illustration?

Pass `icon` (rendered through `SIcon`) or use the `media` slot for arbitrary content:

```vue

```

### How do I add an action button?

Use the `content` (or `default`) slot:

```vue

  <SButton color="primary">New project</SButton>

```

### How do I change the size?

Pass `size` (xs–2xl):

```vue

```

### How do I customize the look?

Use `class`/`ui` for styling or the `custom-styling` demo pattern; pass per-part props to adjust header/media/content individually.

### Is it accessible?

The title is a real heading and the component passes `axe-core` with zero violations; any action you place in the slots keeps its own accessible semantics.

## Form

- Page URL: /components/form
- Markdown URL: /components/form.md
- Description: A form composition layer for building validated forms with a headless core and styled wrappers. The useForm composable is backed by the TanStack Form engine (@tanstack/vue-form) for field-level subscriptions, field arrays, and the submit lifecycle, accepts any Standard Schema validator (Zod, Valibot, ArkType, Yup, …), and returns a context with SFormField / SFormFieldArray used to render the form. Fields register through slots, so any SoybeanUI input (SInput, SSelect, SCheckbox, SSwitch, SRadioGroup, …) or a plain custom control works without a per-control API.

# Form

## Overview

A form composition layer for building validated forms with a headless core and styled wrappers. The `useForm` composable is backed by the **TanStack Form engine** (`@tanstack/vue-form`) — field-level subscriptions, field arrays, and the submit lifecycle come from the engine — and accepts any **Standard Schema** validator (Zod, Valibot, ArkType, Yup, …). It returns a context object with `SFormField` / `SFormFieldArray` used to render the form. Fields register through slots, so any SoybeanUI input (`SInput`, `SSelect`, `SCheckbox`, `SSwitch`, `SRadioGroup`, …) or a plain custom control works without a per-control API.

## Usage

Usage examples for form are rendered on the site.

## Features

- 📜 Schema validation — pass any Standard Schema validator directly (Zod, Valibot, ArkType, Yup); the library has no runtime dependency on `@standard-schema/spec`. The form values type is inferred from the schema, or from `defaultValues` when the schema is omitted
- 🏎️ TanStack engine — field-level subscriptions, array fields, and the submit lifecycle (`isSubmitting` / `isSubmitted` / `submissionAttempts`) are powered by `@tanstack/vue-form`; the full `FormApi` is exposed as `form` for advanced usage (`Subscribe`, `setFieldValue`, `pushFieldValue`, …)
- ✅ Field-level rules — per-field `validate` accepts a sync or async function or a Standard Schema validator, merged with schema errors by the engine; pass it through a Ref / ComputedRef to swap rules reactively
- 🔁 Validate timing — `validateMode` sets when the schema and field-level validators run (`blur` | `change` | `submit`), `validateOnMounted` validates on mount; validators are registered on the engine's async slots, so each validation cause runs them exactly once and async Standard Schemas are supported
- 📦 Field arrays — `append` / `prepend` / `remove` / `insert` / `swap` / `move` / `update` / `replace` with nested path registration (`social[0].name`, TanStack canonical format)
- 🧩 Headless/styled split — `useForm`/`FormCompact` in `@soybeanjs/headless` (zero styles); `SForm*` wrappers inject `formVariants` classes (6 slots: field/fieldArray/label/control/description/error); the error enter/leave animation lives in the UI layer
- ♿ Accessible by default — label `<label :for>` association, `aria-invalid` on error, `aria-describedby` linking description + error to the control
- 🎨 Composable layout — `label` / `control` / `description` / `error` slots plus `*Props` passthrough; `SFormFieldBase` for custom rows
- 🧰 Control-agnostic — fields receive `model-value` + a11y attributes via slot forwarding, so any value-aware control integrates

## Component family

- `useForm` (styled) — the entry composable; returns a context with `form` (TanStack `FormApi`), `state`, `isSubmitting`, `handleSubmit`/`handleReset`, plus the bound `SFormField` / `SFormFieldArray` components
- `SForm` / `FormCompact` (headless) — the `<form>` element owner; forwards `orientation`/`fieldProps`/`fieldArrayProps`/`labelProps`/`controlProps`/`descriptionProps`/`errorProps` to descendants via context
- `SFormField` / `FormFieldCompact` (headless) — registers one field by `name`; owns the field's error/meta and renders label + description + control + error
- `SFormFieldArray` / `FormFieldArrayCompact` (headless) — registers a field array; default slot receives `fields`/`append`/`prepend`/`remove`/`insert`/`swap`/`move`/`update`/`replace`
- `SFormFieldBase` / `FormFieldBaseCompact` (headless) — layout wrapper for custom rows; provides `formFieldId` / `ariaDescribedBy` / `ariaInvalid` to its slot
- `FormField` / `FormLabel` / `FormControl` / `FormDescription` / `FormError` (headless) — low-level primitives used internally by the compact (also exported for custom compositions)
- Core engine — `@tanstack/vue-form` (`FormApi` + Vue `Field` / `Subscribe` / `useSelector`); the former `useHeadlessForm` / `useFormState` / `useFieldArray` self-built engine was retired in v0.50.0

## Demos

Interactive demos for form are rendered on the site.

- 01 Basic — schema-driven form (Zod) with radio/checkbox/switch/select and a nested field array
- 02 Horizontal — horizontal `orientation` layout
- 03 Schema — Zod schema validation with required/min rules
- 04 Rules — field-level `validate` rules next to the schema
- 05 Async — async field-level validation (e.g. uniqueness check)
- 06 Array — dynamic list with append/remove/move controls
- 07 Disabled — field-level `disabled` on input/select/checkbox

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (10): Form, FormCompact, FormControl, FormDescription, FormError, FormField, FormFieldArrayCompact, FormFieldBaseCompact, FormFieldCompact, FormLabel.

### Form

#### Props
Properties for the FormCompact component.
- `class`: Additional class names applied to the form element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<FormUi>`; optional)
- `fieldProps`: No description. (type `FormFieldProps`; optional)
- `fieldArrayProps`: No description. (type `FormFieldProps`; optional)
- `orientation`: Orientation of the form field. (type `DataOrientation`; default `'vertical'`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `FormDescriptionProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `FormLabelProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `FormControlProps`; optional)
- `errorProps`: Properties forwarded to the error element. (type `FormErrorProps`; optional)

### FormCompact

#### Props
Properties for the FormCompact component.
- `fieldProps`: No description. (type `FormFieldProps`; optional)
- `fieldArrayProps`: No description. (type `FormFieldProps`; optional)
- `orientation`: Orientation of the form field. (type `DataOrientation`; default `'vertical'`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `FormDescriptionProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `FormLabelProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `FormControlProps`; optional)
- `errorProps`: Properties forwarded to the error element. (type `FormErrorProps`; optional)

### FormControl

- No documented props, emits, slots, or slot props were available.

### FormDescription

- No documented props, emits, slots, or slot props were available.

### FormError

- No documented props, emits, slots, or slot props were available.

### FormField

#### Props
Properties for the FormField component.
- `error`: Error. (type `string`; optional)
- `isFieldArray`: Whether the field is an array. (type `boolean`; optional)
#### Slots
Slots for the FormField component.
- `default`: Custom content for the default slot. (type `((props: FormFieldState<any, any>) => any) | undefined`)
- `label`: Custom content for the label slot. (type `((props: FormFieldState<any, any>) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: FormFieldState<any, any>) => any) | undefined`)
- `error`: Custom content for the error slot. (type `((props: { error: string | undefined; errorProps: FormErrorProps; }) => any) | undefined`)

### FormFieldArrayCompact

#### Slots
Slots for the FormFieldArrayCompact component.
- `default`: Custom content for the default slot. (type `((props: FormFieldArrayStates<Values, Name>) => any) | undefined`)
- `label`: Custom content for the label slot. (type `((props: FormFieldArrayStates<Values, Name>) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: FormFieldArrayStates<Values, Name>) => any) | undefined`)
- `error`: Custom content for the error slot. (type `((props: { error: string | undefined; errorProps: FormErrorProps; }) => any) | undefined`)

### FormFieldBaseCompact

#### Props
Properties for the FormFieldBaseCompact component.
- `error`: Error. (type `string`; optional)
- `isFieldArray`: Whether the field is an array. (type `boolean`; optional)
- `orientation`: Orientation of the form field. (type `DataOrientation`; default `'vertical'`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `labelProps`: Properties forwarded to the label element. (type `FormLabelProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `FormControlProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `FormDescriptionProps`; optional)
- `errorProps`: Properties forwarded to the error element. (type `FormErrorProps`; optional)
#### Slots
Slots for the FormFieldBaseCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `label`: Custom content for the label slot. (type `(() => any) | undefined`)
- `description`: Custom content for the description slot. (type `(() => any) | undefined`)
- `error`: Custom content for the error slot; falls back to a plain FormError. (type `((props: { error: string | undefined; errorProps: FormErrorProps; }) => any) | undefined`)

### FormFieldCompact

#### Props
Properties for the FormFieldCompact component.
- `name`: The name of the form field, used for registration and value retrieval. (type `Name`; required)
- `isFieldArray`: Whether the field is an array. (type `boolean`; optional)
- `orientation`: Orientation of the form field. (type `DataOrientation`; default `'vertical'`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `labelProps`: Properties forwarded to the label element. (type `FormLabelProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `FormControlProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `FormDescriptionProps`; optional)
- `errorProps`: Properties forwarded to the error element. (type `FormErrorProps`; optional)
- `validate`: Field-level validator. May be a sync or async function, a Standard Schema validator, or a Ref / ComputedRef of either for reactive rebinding. (type `FormFieldValidateSource<DeepValue<Values, Name>>`; optional)
#### Slots
Slots for the FormFieldCompact component.
- `default`: Custom content for the default slot. (type `((props: FormFieldState<Values, Name>) => any) | undefined`)
- `label`: Custom content for the label slot. (type `((props: FormFieldState<Values, Name>) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: FormFieldState<Values, Name>) => any) | undefined`)
- `error`: Custom content for the error slot. (type `((props: { error: string | undefined; errorProps: FormErrorProps; }) => any) | undefined`)

### FormLabel

#### Props
Properties for the FormLabel component.
- `for`: The id of the element the label is associated with. (type `string`; optional)

## Notes

### Architecture and benchmark differences

`useForm` wraps TanStack's `useForm`: the schema is registered as a form-level validator and each field-level `validate` as a field validator, and the engine owns values, field meta, error distribution by path, and the submit lifecycle. `validateMode` maps onto a TanStack validator timing (`onChange` / `onBlur` / `onSubmit`); the schema is registered on the async slots, which also accept sync returns, so each validator runs exactly once per validation cause and async Standard Schemas work. Submit-cause field slots are always attached so `handleSubmit` awaits field validation. `useFieldArray` exposes mutation helpers built on the engine's array operations (`pushFieldValue`, `insertFieldValue`, `removeFieldValue`, `swapFieldValues`, `moveFieldValues`, `replaceFieldValue`). `FormFieldBaseCompact` merges `fieldProps`/`labelProps`/`controlProps`/`descriptionProps`/`errorProps` from the form context and injects a11y state (`aria-invalid`, `aria-describedby`) into the control slot; the error enter/leave height-collapse animation is composed in the UI layer. Most benchmark libraries couple the schema validator to a framework-specific rule object; the Standard Schema interface plus the headless/styled split on top of a mainstream engine are the differentiators.

| Capability                          | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | React Hook Form |
| :---------------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :-------------: |
| headless/styled split               |    ✅     |     —      |      —       |    —    |    —     |        —        |
| Standard Schema (Zod/Valibot…)      |    ✅     |     ⚠️     |      —       |   ✅    |    —     |       ✅        |
| Field-level sync/async rules        |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |       ✅        |
| `validateMode`                      |    ✅     |     ⚠️     |      ✅      |    —    |    ✅    |        —        |
| Field array (append/remove/move)    |    ✅     |     ✅     |      —       |   ✅    |    —     |       ✅        |
| Nested path registration            |    ✅     |     ✅     |      —       |    —    |    —     |       ✅        |
| Submitting state (`isSubmitting`)   |    ✅     |     —      |      —       |   ✅    |    —     |       ✅        |
| `aria-invalid` + `aria-describedby` |    ✅     |     —      |      —       |   ✅    |    —     |        —        |
| Per-part slots + `*Props`           |    ✅     |     ⚠️     |      —       |    —    |    —     |        —        |

`⚠️` = partial (Ant Design covers most rules via `rules`/`validateTrigger` but has no Standard Schema; its `required`/`colon`/`labelAlign`/`labelWidth`/`layout` are style-level conveniences that SoybeanUI keeps out of the core).

### Migration from v0.4x (`useHeadlessForm` → TanStack Form)

v0.50.0 replaces the self-built `useHeadlessForm` engine with `@tanstack/vue-form`. The component surface (`SForm` / `SFormField` / `SFormFieldArray` / `SFormFieldBase`, label/description/error wiring, a11y attributes) is unchanged; the hook surface changed:

| v0.4x                                                                                                      | v0.50.0                                                                                                                                                                                                           |
| :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useForm(options, Field, FieldArray)` returning a tuple                                                    | `useForm(options)` returning a context object; styled components come back as `SFormField` / `SFormFieldArray` properties                                                                                         |
| `initialValues`                                                                                            | renamed to `defaultValues` (TanStack-native naming); reset restores them                                                                                                                                          |
| `onSubmit(values, helper)`                                                                                 | `onSubmit(values)` — the `FormSubmitHelper` was removed; TanStack owns the submitting lifecycle                                                                                                                   |
| `initialErrors` / `initialTouched` / `resetForm(nextState)`                                                | removed; use `form.setFieldMeta` / `form.reset()` from the exposed TanStack `FormApi`                                                                                                                             |
| `formState.values` / `errors` / `touched` refs                                                             | the `state` snapshot on the `useForm` return was removed; read reactive state via `form.useSelector(state => …)` / `form.Subscribe` (the raw `form.state` snapshot still lives on the exposed TanStack `FormApi`) |
| `setValues` / `setFieldValue` / `setFieldTouched` / `getFieldValue` / `validateForm` / `validateField`     | TanStack `FormApi` methods on `form`: `setFieldValue`, `getFieldValue`, `validate`, `resetField`, …                                                                                                               |
| `reValidateMode`                                                                                           | removed; with the default `submit` mode errors refresh on every submit — use `validateMode: 'change'` for live re-validation                                                                                      |
| field-level `reset` callback option                                                                        | removed; `handleReset` restores `defaultValues` and field values re-sync through the engine                                                                                                                       |
| `useField(name)` returning `Ref<FormFieldState>`                                                           | `useField(name)` returning a computed of `{ name, value, meta: { dirty, error, touched }, handleChange, onBlur }`                                                                                                 |
| `useFieldArray(name)` returning `{ fields, append, prepend, remove, swap, move, insert, update, replace }` | same shape; `fields` entries are `{ key, name, value }`                                                                                                                                                           |
| Field-array nested paths `social.0.name`                                                                   | TanStack canonical format `social[0].name` (array segments bracketed)                                                                                                                                             |
| `errors` keyed by dotted paths                                                                             | `onInvalid` errors (and `form.state.fieldMeta`) are keyed by the canonical TanStack path (bracketed array segments)                                                                                               |

### Cautions

- `useForm` returns a context object — destructure by name: `const { handleSubmit, SFormField, SFormFieldArray, isSubmitting } = useForm({...})`.
- For reactive form-state reads use `form.useSelector(state => …)`; `form.state` itself is a TanStack Store snapshot without Vue reactivity.
- Validation timing: the `validateMode` timing applies statically; with the default `submit` mode errors appear after a submit attempt and refresh on each submit — set `validateMode: 'change'` for live re-validation. Validation runs through the engine's async slots, so results settle an async tick after the triggering event.
- When the schema reports issues without a field path (e.g. cross-field refinements), `onInvalid` errors expose them under the `_form` key.
- Advanced TanStack `FormOptions` can be passed declaratively via `formOptions` (e.g. `asyncDebounceMs`, `canSubmitWhenInvalid`, `listeners`); the wrapper-owned fields (`defaultValues` / `validators` / `onSubmit` / `onSubmitInvalid`) are excluded and always win.
- Array item errors are stored under bracketed keys (`emails[0]`) and do not bubble to the array root — validate the whole array (e.g. `min(1)`) at the array level, or render per-item errors with nested `SFormField`s using the bracketed path.
- With Zod v4, `z.number()` does not coerce string values — a text input reports `"Invalid input: expected number"`. Use `z.coerce.number()` (or parse the value) when the control is an `<input type="text">`.
- The control slot is value-agnostic: fields forward `model-value` (and `aria-invalid`/`aria-describedby`). Custom controls must accept and emit `modelValue`.
- The form element itself renders only `data-soybean-form`/`data-orientation` — validation styles live on the field/control/error parts, so style it with the `SForm` `ui`/`class` props.
- Field-level `validate` merges with the schema in the engine's error map — pass a function (return `undefined` for valid) or a Standard Schema validator; a Ref / ComputedRef source rebinds rules reactively.
- Disabling is control-level: `disabled` on the input blocks interaction but the field still validates on submit unless you also gate the value.

## FAQ

### How do I switch between Zod and Valibot?

You don't — pass the schema directly. Standard Schema validators are accepted as-is: `useForm({ schema: zodSchema })` or `useForm({ schema: valibotSchema })` behave identically.

### How do I validate on input instead of on submit?

Set `validateMode: 'change'` (or `'blur'`). The timing applies statically from the first interaction — the "validate live" pattern; with the default `submit` mode errors appear after submit attempts and refresh on each submit.

### How do I build a dynamic list of fields?

Use `SFormFieldArray`:

```vue

  <template #default="{ fields, append, remove, move }">
    <div v-for="(field, index) in fields" :key="index">
      <SFormField :name="`${field.name}[${index}].name`" label="Name">
        <SInput />
      </SFormField>
      <SButtonIcon icon="lucide:minus" @click="remove(index)" />
    </div>
    <SButtonIcon icon="lucide:plus" @click="append({ name: '', url: '' })" />
  </template>

```

### How do I show a loading state while submitting?

`isSubmitting` flips to `true` during the async `onSubmit` and back after it resolves — disable the submit button or show a spinner:

```vue

  <SButton type="submit" :loading="isSubmitting">Submit</SButton>

```

### Why does my number input report "Invalid input: expected number"?

The input value is a string. With Zod v4 use `z.coerce.number()` (then `.min(...)`), or write a field-level `validate` that parses first.

### How do I reset the form to initial values?

Bind `on-reset` on `SForm` to `handleReset` (returned by `useForm`). Reset restores `defaultValues`, clears errors/touched, and keeps the field values in sync with the controls.

## Hover Card

- Page URL: /components/hover-card
- Markdown URL: /components/hover-card.md
- Description: Displays a richer preview card when the trigger is hovered or receives focus. SHoverCard combines the headless HoverCardRoot/HoverCardTrigger/HoverCardPositioner/HoverCardPopup/HoverCardArrow primitive family (built on the shared Popper) with the hoverCardVariants style recipe (3 slots, 6 sizes).

# Hover Card

## Overview

Displays a richer preview card when the trigger is hovered or receives focus. `SHoverCard` combines the headless `HoverCardRoot`/`HoverCardTrigger`/`HoverCardPositioner`/`HoverCardPopup`/`HoverCardArrow` primitive family (built on the shared `Popper`) with the `hoverCardVariants` style recipe (3 slots, 6 sizes).

Use a hover card for a non-blocking, hover-triggered preview (user profiles, repository previews, inline metadata). For a small text hint use `tooltip`; for click-triggered rich content use `popover`.

## Usage

Usage examples for hover-card are rendered on the site.

## Features

- 🧩 Headless/styled split — `HoverCardCompact` aggregates the popper trigger, positioner, popup and arrow; `SHoverCard` only injects styles and forwards slots/events
- ⏱️ Open/close delay — `openDelay` (default 700ms) / `closeDelay` (default 300ms) tune the hover latency
- 🎯 Placement — full popper `placement` control with collision avoidance and side-aware slide animations
- 🔽 Arrow — `showArrow` renders a positioned arrow; configurable via `arrowProps`
- ⌨️ Focus trigger — also opens on keyboard focus, not just pointer hover
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ♿ Accessible — dismiss on Escape/outside interaction, `axe-core` zero violations open and closed

## Component family

- `SHoverCard` (styled) — the entry wrapper; `hoverCardVariants` recipe with dynamic slot forwarding
- `HoverCardRoot` (headless) — the state owner; `open` via `useControllableState`, `openDelay`/`closeDelay`, provides the popper root
- `HoverCardTrigger` (headless) — the anchor that opens the card on hover/focus
- `HoverCardPositioner` / `HoverCardPositionerImpl` (headless) — the dismissable, positioned surface (built on `PopperPositioner`)
- `HoverCardPopup` (headless) — the popup body
- `HoverCardArrow` (headless) — the popper arrow
- `HoverCardCompact` (headless) — the aggregated composite; composes trigger/positioner/popup/arrow and exposes the slots

## Demo

Interactive demos for hover-card are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (8): HoverCard, HoverCardArrow, HoverCardCompact, HoverCardPopup, HoverCardPortal, HoverCardPositioner, HoverCardRoot, HoverCardTrigger.

### HoverCard

#### Props
Properties for the HoverCard component.
- `class`: class of popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<HoverCardUi>`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopperAnchorProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `HoverCardPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `HoverCardPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `HoverCardPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `HoverCardArrowProps`; optional)
- `defaultOpen`: The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the hover card. (type `boolean`; optional)
- `openDelay`: The duration from when the pointer enters the trigger until the hover card opens. (type `number`; optional)
- `closeDelay`: The duration from when the pointer leaves the trigger or popup until the hover card closes. (type `number`; optional)
- `dir`: No description. (type `Direction`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the HoverCard component.
- `update:open`: Event handler called when the open state of the hover card changes. (type `[value: boolean, reason?: PopperOpenChangeReason | undefined]`; parameters `value: boolean, reason?: PopperOpenChangeReason | undefined`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
#### Slots
Slots for the HoverCard component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `(() => any) | undefined`)

### HoverCardArrow

- No documented props, emits, slots, or slot props were available.

### HoverCardCompact

#### Props
Properties for the HoverCardCompact component.
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopperAnchorProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `HoverCardPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `HoverCardPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `HoverCardPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `HoverCardArrowProps`; optional)
- `defaultOpen`: The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the hover card. (type `boolean`; optional)
- `openDelay`: The duration from when the pointer enters the trigger until the hover card opens. (type `number`; optional)
- `closeDelay`: The duration from when the pointer leaves the trigger or popup until the hover card closes. (type `number`; optional)
- `dir`: No description. (type `Direction`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the HoverCardCompact component.
- `update:open`: Event handler called when the open state of the hover card changes. (type `[value: boolean, reason?: PopperOpenChangeReason | undefined]`; parameters `value: boolean, reason?: PopperOpenChangeReason | undefined`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
#### Slots
Slots for the HoverCardCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `(() => any) | undefined`)

### HoverCardPopup

- No documented props, emits, slots, or slot props were available.

### HoverCardPortal

- No documented props, emits, slots, or slot props were available.

### HoverCardPositioner

#### Props
Properties for the HoverCardPositioner component.
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the HoverCardPositioner component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)

### HoverCardRoot

#### Props
Properties for the HoverCardRoot component.
- `defaultOpen`: The open state of the hover card when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the hover card. (type `boolean`; optional)
- `openDelay`: The duration from when the pointer enters the trigger until the hover card opens. (type `number`; optional)
- `closeDelay`: The duration from when the pointer leaves the trigger or popup until the hover card closes. (type `number`; optional)
- `dir`: No description. (type `Direction`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the HoverCardRoot component.
- `update:open`: Event handler called when the open state of the hover card changes. (type `[value: boolean, reason?: PopperOpenChangeReason | undefined]`; parameters `value: boolean, reason?: PopperOpenChangeReason | undefined`)

### HoverCardTrigger

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`HoverCardCompact` owns the trigger/positioner/popup/arrow composition while every primitive stays style-free and only the UI wrapper injects the `hoverCardVariants` classes. This mirrors radix-ui/shadcn-ui's headless split, built on the shared `Popper` primitives. Ant Design, Element Plus, Mantine and Naive UI ship a single styled popover used for hover previews; SoybeanUI exposes a dedicated hover-card with configurable `openDelay`/`closeDelay`, per-slot `*Props`, an arrow toggle and a `size` scale the single-package libraries generally omit.

| Capability            | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :-------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Open/close delay      |    ✅     |    ✅     |     —      |      —       |   ✅    |    —     |
| Popper placement (12) |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |
| Arrow                 |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Sizes (6)             |    ✅     |     —     |     —      |      —       |    —    |    —     |
| Focus trigger         |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |

`—` = unsupported or a different interaction model (hover previews fold into the generic popover).

### Cautions

- The card opens on hover and keyboard focus; tune `openDelay`/`closeDelay` to reduce accidental triggers (defaults 700ms/300ms).
- The popup is rendered through a `Portal` (teleported to `document.body`); position it inside a relatively-positioned ancestor only with `portalProps: { disabled: true }`.
- `showArrow` renders an arrow; `arrowProps` can override its position/classes.
- The hover card is non-modal and dismisses on Escape or outside interaction; it does not trap focus.

### Roadmap

N/A — hover-card is feature-complete for the current parity set.

## FAQ

### How do I adjust the open/close timing?

Set `open-delay` and `close-delay` (ms):

```vue

  <template #trigger><SButton>Hover me</SButton></template>
  <div>Preview content</div>

```

### How do I position the card?

Use `placement`:

```vue

  <template #trigger><SButton>Hover me</SButton></template>
  <div>Preview content</div>

```

### How do I hide the arrow?

Set `show-arrow={false}`:

```vue

  <template #trigger><SButton>Hover me</SButton></template>
  <div>Preview content</div>

```

### How do I control the open state?

Bind `open` with `v-model` or use `defaultOpen`:

```vue

  <template #trigger><SButton>Hover me</SButton></template>
  <div>Preview content</div>

```

## Icon

- Page URL: /components/icon
- Markdown URL: /components/icon.md
- Description: SIcon is a unified icon component built on top of Iconify. It supports rendering icons from the Iconify dataset or custom components/VNodes. It integrates with SConfigProvider for consistent sizing across the application.

# Icon

## Overview

`SIcon` is a unified icon component built on top of [Iconify](https://iconify.design/). It supports rendering icons from the Iconify dataset or custom components/VNodes. It integrates with `SConfigProvider` for consistent sizing across the application.

## Features

- 📦 **Iconify Support**: Render any icon from the massive Iconify library.
- 🔧 **Custom Icons**: Support for Vue components, VNodes, or raw strings.
- 📏 **Global Sizing**: Inherits default size from `SConfigProvider`.
- 🎨 **Styling**: Easy customization via props or CSS classes.
- ♿ **Accessibility**: Decorative icons are `aria-hidden` by default; semantic icons are exposed via `aria-label` / `aria-labelledby`.

## Basic Usage

### Using Iconify Name

```vue
<script setup lang="ts">
import { SIcon } from '@soybeanjs/ui';
</script>

<template>
  <SIcon icon="lucide:home" />
  <SIcon icon="mdi:account" class="text-primary" />
</template>
```

### Custom Size

```vue
<template>
  <SIcon icon="lucide:settings" width="24" height="24" />
</template>
```

You can also set a default size globally via `SConfigProvider`:

```vue
<script setup lang="ts">
import { SConfigProvider, SIcon } from '@soybeanjs/ui';
</script>

<template>
  <SConfigProvider :iconify="{ width: '1.5rem', height: '1.5rem' }">
    <SIcon icon="lucide:home" />
  </SConfigProvider>
</template>
```

### Custom Icon Component

```vue
<script setup lang="ts">
import { SIcon } from '@soybeanjs/ui';
import CustomIcon from './CustomIcon.vue';
</script>

<template>
  <SIcon :icon="CustomIcon" />
</template>
```

## Accessibility

- **Decorative icons** (default): `aria-hidden="true"` is set automatically, hiding the icon from assistive technology.
- **Semantic icons**: pass `aria-label` or `ariaLabelledby` and `aria-hidden` will not be set, making the icon visible to assistive technology.

```vue
<template>
  
  <SIcon icon="lucide:check" />

  
  <SIcon icon="lucide:check" aria-label="Completed" />
</template>
```

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Icon.

### Icon

#### Props
Properties for the Icon component.
- `icon`: Icon rendered by the component. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; required)
- `ariaHidden`: Whether the icon is hidden from assistive technology. Defaults to `true` for decorative icons. Set to `false` or provide `ariaLabel` / `ariaLabelledby` to expose the icon. (type `boolean`; optional)
- `ariaLabel`: Accessible label for the icon. When provided, `aria-hidden` is not set so the label is announced. (type `string`; optional)
- `ariaLabelledby`: ID of an element that labels the icon. When provided, `aria-hidden` is not set so the label is announced. (type `string`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the icon into a headless layer (`_icon` in `@soybeanjs/headless`, providing the `IconValue` type and render hook) and a styled layer (`SIcon` in `@soybeanjs/ui`, wrapping Iconify rendering, size inheritance, and accessibility logic). This differs from single-package libraries such as Ant Design, Element Plus, MUI, Mantine, and Naive UI.

| Aspect        | SoybeanUI                                                         | Ant Design / Element Plus / MUI / Mantine / Naive UI |
| :------------ | :---------------------------------------------------------------- | :--------------------------------------------------- |
| Architecture  | headless + styled split                                           | single package                                       |
| Icon source   | Iconify (200+ icon sets, on-demand loading)                       | built-in icon set / custom SVG                       |
| Styling       | UnoCSS utility classes                                            | CSS-in-JS / SCSS / CSS vars                          |
| Sizing        | prop + `SConfigProvider` global inheritance                       | prop / token                                         |
| Accessibility | decorative/semantic auto-distinction, smart `aria-hidden` default | manual `aria-label`                                  |

### FAQ

**Why is `aria-hidden="true"` set by default?**
Most icons are decorative and serve only as visual aids. Defaulting to `aria-hidden="true"` prevents screen readers from announcing meaningless icon names. When an icon carries semantic meaning, pass `aria-label` or `ariaLabelledby` and `aria-hidden` is automatically removed.

**How do I use an Iconify string name?**
Pass a string in the `icon="prefix:name"` format, e.g. `icon="lucide:home"`. Iconify loads the icon data on demand from its API. You can also pre-register icon data via `addIcon` / `addCollection` for offline use.

**How do I rotate or flip an icon?**
Use `hFlip` for a horizontal mirror, `vFlip` for a vertical mirror, `rotate` for rotation, and `inline` for baseline alignment. These props are forwarded to Iconify:

```vue
<template>
  <SIcon icon="lucide:arrow-right" :h-flip="true" />
  <SIcon icon="lucide:refresh-cw" rotate="90deg" />
  <SIcon icon="lucide:home" inline />
</template>
```

`rotate` accepts a string (e.g. `"90deg"`) or a number of quarter turns (e.g. `1` for 90°, `2` for 180°).

**How does `SConfigProvider` size priority work?**
The `width` / `height` props passed directly take precedence over the `iconify.width` / `iconify.height` configured in `SConfigProvider`.

**Is SSR supported?**
Yes. The Iconify component renders an empty placeholder in SSR environments and loads icon data after client hydration. For instant SSR rendering, pre-register icon data.

## Input

- Page URL: /components/input
- Markdown URL: /components/input.md
- Description: A single-line text input that collects user input, supporting standard input attributes, prefix/suffix slots, and clearable functionality. Use it for any short free-text entry — form fields, search boxes, filters. For multi-line text use STextarea; for sensitive values use SPassword; for numeric values use SInputNumber.

# Input

## Overview

A single-line text input that collects user input, supporting standard input attributes, prefix/suffix slots, and clearable functionality. Use it for any short free-text entry — form fields, search boxes, filters. For multi-line text use `STextarea`; for sensitive values use `SPassword`; for numeric values use `SInputNumber`.

## Usage

Usage examples for input are rendered on the site.

## Features

- 📏 6 sizes: xs, sm, md, lg, xl, 2xl
- 🧹 Clearable mode with a hover/focus-revealed clear button (i18n `aria-label`)
- 🔤 `leading` / `trailing` slots for prefix and suffix content
- 🔒 `disabled` / `readonly` states with full interaction guards
- 📋 Native form submission via a proxied hidden input when `name` is set
- ♿ Full accessibility support — `aria-roledescription`, clear button naming, axe-clean
- 🎯 TypeScript type safety with strict `type` attribute typing

## Input component family

- **SInput** - Base text input component
- **SInputClear** - Clear button, shown on hover/focus when `clearable`

## Demos

Interactive demos for input are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Input, InputClear, InputCompact, InputControl, InputRoot.

### Input

#### Props
Properties for the Input component.
- `class`: root class (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<InputUi>`; optional)
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputControlProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `InputClearProps`; optional)
- `defaultValue`: The default value of the input (type `string`; optional)
- `modelValue`: The controlled value of the input (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the Input component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the Input component.
- `leading`: Custom content for the leading slot. (type `((props: InputCompactSlotProps) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: InputCompactSlotProps) => any) | undefined`)
- `clear`: Custom content for the clear slot. (type `((props: InputCompactSlotProps) => any) | undefined`)

### InputClear

#### Props
Properties for the InputClear component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the InputClear component.
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### InputCompact

#### Props
Properties for the InputCompact component.
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputControlProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `InputClearProps`; optional)
- `defaultValue`: The default value of the input (type `string`; optional)
- `modelValue`: The controlled value of the input (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the InputCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the InputCompact component.
- `leading`: Custom content for the leading slot. (type `((props: InputCompactSlotProps) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: InputCompactSlotProps) => any) | undefined`)
- `clear`: Custom content for the clear slot. (type `((props: InputCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the InputCompact component.
- `modelValue`: Current model value. (type `string`; optional)
- `clear`: Clear handler. (type `() => void`; required)

### InputControl

- No documented props, emits, slots, or slot props were available.

### InputRoot

#### Props
Properties for the InputRoot component.
- `defaultValue`: The default value of the input (type `string`; optional)
- `modelValue`: The controlled value of the input (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the InputRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the input into a headless layer (`@soybeanjs/headless/input`) that owns state, form proxying, and clear-button semantics, and a styled layer (`@soybeanjs/ui`) that owns variants and UnoCSS classes. The headless `InputCompact` composes `InputRoot` / `InputControl` / `InputClear` and exposes `leading` / `clear` / `trailing` slots, mirroring the headless/styled split of Radix and differing from single-package libraries such as Ant Design and Element Plus.

| Capability                     | SoybeanUI | Ant Design `Input` | Element Plus `Input` | Radix `TextField` |
| :----------------------------- | :-------: | :----------------: | :------------------: | :---------------: |
| headless/styled split          |    ✅     |         —          |          —           |        ✅         |
| Controlled / uncontrolled      |    ✅     |         ✅         |          ✅          |        ✅         |
| Clear button (hover reveal)    |    ✅     |         ✅         |          ✅          |         —         |
| Clear button i18n `aria-label` |    ✅     |         ✅         |          —           |         —         |
| Prefix / suffix slots          |    ✅     |         ✅         |          ✅          |        ✅         |
| Native form proxying           |    ✅     |         —          |          —           |         —         |
| Size variants                  |    ✅     |         ✅         |          ✅          |         —         |
| `showCount` counter            |     —     |         ✅         |          ✅          |         —         |
| `error` / `loading` state      |     —     |         ✅         |          ✅          |         —         |

### Cautions

- `showCount`, `error`, and `loading` states are not implemented; they are tracked as enhancement backlog.
- The clear button only appears on hover or focus (desktop convention); on touch devices ensure a `leading`/`trailing` affordance if needed.
- The root renders `role="group"` with `aria-roledescription="Input"` and `spellcheck="false"` by design.

## FAQ

### How do I add a prefix icon or suffix text?

Use the `leading` and `trailing` slots. They receive the root context and render inside the input field frame.

### Why does the clear button only show on hover?

Clear visibility follows the desktop hover/focus convention (`group-hover` / `group-focus-within`). It is intentionally not always visible to keep the input compact and avoid accidental clearing.

### How does the input submit its value in a native form?

Pass `name` — the component renders a visually hidden proxy input carrying the current value, so native form submission and validation work without extra wiring.

### How do I limit the input length?

Pass `maxlength` / `minlength`; they are forwarded to the native input. A visible counter is not yet provided (tracked as enhancement backlog).

## InputNumber

- Page URL: /components/input-number
- Markdown URL: /components/input-number.md
- Description: A numeric input field that only accepts numeric values, with increment/decrement controls, keyboard interaction, and min/max boundary handling. Use it for quantities, prices, ages, or any value that must stay numeric and within a range. For general text use SInput.

# InputNumber

## Overview

A numeric input field that only accepts numeric values, with increment/decrement controls, keyboard interaction, and min/max boundary handling. Use it for quantities, prices, ages, or any value that must stay numeric and within a range. For general text use `SInput`.

## Usage

Usage examples for input-number are rendered on the site.

## Features

- 📏 6 sizes: xs, sm, md, lg, xl, 2xl
- 🎚 Step buttons with press-and-hold acceleration (400ms → 60ms loop)
- ⌨️ Full keyboard support — Arrow keys, Page Up/Down, Home/End, Enter, wheel
- ⚖️ `min` / `max` clamping with disabled buttons at boundaries, `step`, `formatOptions` precision
- 🌐 Locale-aware formatting via `Intl.NumberFormat`
- 🧹 Clearable mode with an i18n `aria-label` clear button
- 📋 Native form submission via a proxied hidden input when `name` is set
- ♿ Full accessibility support — `aria-valuemin/max/now`, clear naming, axe-clean

## Demos

Interactive demos for input-number are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): InputNumber, InputNumberClear, InputNumberCompact, InputNumberControl, InputNumberDecrement, InputNumberIncrement, InputNumberRoot.

### InputNumber

#### Props
Properties for the InputNumber component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<InputNumberUi>`; optional)
- `center`: Whether to center the input. (type `boolean`; default `false`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputNumberControlProps`; optional)
- `incrementProps`: Properties forwarded to the increment element. (type `InputNumberIncrementProps`; optional)
- `decrementProps`: Properties forwarded to the decrement element. (type `InputNumberDecrementProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `ButtonProps`; optional)
- `defaultValue`: The default value of the input (type `number`; optional)
- `modelValue`: The controlled value of the input (type `number | null`; optional)
- `min`: The smallest value allowed for the input. (type `number`; optional)
- `max`: The largest value allowed for the input. (type `number`; optional)
- `step`: The amount that the input value changes with each increment or decrement "tick". (type `number`; optional)
- `stepSnapping`: When `false`, prevents the value from snapping to the nearest increment of the step value (type `boolean`; optional)
- `focusOnChange`: When `true`, the input will be focused when the value changes. (type `boolean`; optional)
- `formatOptions`: Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. (type `Intl.NumberFormatOptions`; optional)
- `locale`: The locale to use for formatting dates (type `string`; optional)
- `disableWheelChange`: When `true`, prevents the value from changing on wheel scroll. (type `boolean`; optional)
- `invertWheelChange`: When `true`, inverts the direction of the wheel change. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element. (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the InputNumber component.
- `update:modelValue`: Emitted when the model value changes. (type `[val: number | null]`; parameters `val: number | null`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the InputNumber component.
- `leading`: Custom content for the leading slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `clear`: Custom content for the clear slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `decrement`: Custom content for the decrement slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `increment`: Custom content for the increment slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)

### InputNumberClear

#### Props
Properties for the InputNumberClear component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the InputNumberClear component.
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### InputNumberCompact

#### Props
Properties for the InputNumberCompact component.
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputNumberControlProps`; optional)
- `incrementProps`: Properties forwarded to the increment element. (type `InputNumberIncrementProps`; optional)
- `decrementProps`: Properties forwarded to the decrement element. (type `InputNumberDecrementProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `ButtonProps`; optional)
- `defaultValue`: The default value of the input (type `number`; optional)
- `modelValue`: The controlled value of the input (type `number | null`; optional)
- `min`: The smallest value allowed for the input. (type `number`; optional)
- `max`: The largest value allowed for the input. (type `number`; optional)
- `step`: The amount that the input value changes with each increment or decrement "tick". (type `number`; optional)
- `stepSnapping`: When `false`, prevents the value from snapping to the nearest increment of the step value (type `boolean`; optional)
- `focusOnChange`: When `true`, the input will be focused when the value changes. (type `boolean`; optional)
- `formatOptions`: Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. (type `Intl.NumberFormatOptions`; optional)
- `locale`: The locale to use for formatting dates (type `string`; optional)
- `disableWheelChange`: When `true`, prevents the value from changing on wheel scroll. (type `boolean`; optional)
- `invertWheelChange`: When `true`, inverts the direction of the wheel change. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element. (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the InputNumberCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[val: number | null]`; parameters `val: number | null`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the InputNumberCompact component.
- `leading`: Custom content for the leading slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `clear`: Custom content for the clear slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `decrement`: Custom content for the decrement slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
- `increment`: Custom content for the increment slot. (type `((props: InputNumberCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the InputNumberCompact component.
- `modelValue`: Current model value. (type `number | null`; optional)
- `clear`: Clear handler. (type `() => void`; required)

### InputNumberControl

- No documented props, emits, slots, or slot props were available.

### InputNumberDecrement

#### Props
Properties for the InputNumberDecrement component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### InputNumberIncrement

#### Props
Properties for the InputNumberIncrement component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### InputNumberRoot

#### Props
Properties for the InputNumberRoot component.
- `defaultValue`: The default value of the input (type `number`; optional)
- `modelValue`: The controlled value of the input (type `number | null`; optional)
- `min`: The smallest value allowed for the input. (type `number`; optional)
- `max`: The largest value allowed for the input. (type `number`; optional)
- `step`: The amount that the input value changes with each increment or decrement "tick". (type `number`; optional)
- `stepSnapping`: When `false`, prevents the value from snapping to the nearest increment of the step value (type `boolean`; optional)
- `focusOnChange`: When `true`, the input will be focused when the value changes. (type `boolean`; optional)
- `formatOptions`: Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user. (type `Intl.NumberFormatOptions`; optional)
- `locale`: The locale to use for formatting dates (type `string`; optional)
- `disableWheelChange`: When `true`, prevents the value from changing on wheel scroll. (type `boolean`; optional)
- `invertWheelChange`: When `true`, inverts the direction of the wheel change. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element. (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the InputNumberRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[val: number | null]`; parameters `val: number | null`)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the input-number into a headless layer (`@soybeanjs/headless/input-number`) that owns state, number parsing/formatting, boundary logic, and form proxying, and a styled layer (`@soybeanjs/ui`) that owns variants and UnoCSS classes. The headless `InputNumberCompact` composes `InputNumberRoot` / `InputNumberControl` / `InputNumberIncrement` / `InputNumberDecrement` / `InputNumberClear` and exposes `increment` / `decrement` / `clear` slots. This mirrors the headless/styled split and differs from single-package libraries such as Ant Design, Element Plus, and Mantine.

| Capability                       | SoybeanUI | Ant Design `InputNumber` | Element Plus `input-number` | Mantine `NumberInput` |
| :------------------------------- | :-------: | :----------------------: | :-------------------------: | :-------------------: |
| headless/styled split            |    ✅     |            —             |              —              |           —           |
| Controlled / uncontrolled        |    ✅     |            ✅            |             ✅              |          ✅           |
| step / min / max / precision     |    ✅     |            ✅            |             ✅              |          ✅           |
| Keyboard Arrow/Page/Home/End     |    ✅     |            ✅            |             ✅              |          ✅           |
| Press-and-hold acceleration      |    ✅     |            ✅            |              —              |           —           |
| Boundary button disabling        |    ✅     |            —             |             ✅              |           —           |
| Clear button (i18n `aria-label`) |    ✅     |            —             |             ✅              |           —           |
| Locale-aware format (Intl)       |    ✅     |            —             |              —              |           —           |
| Size variants (xs…2xl)           |    ✅     |            —             |              —              |          ✅           |
| `center` layout                  |    ✅     |            ✅            |             ✅              |           —           |

### Cautions

- `formatter` / `parser` hooks, `controls` visibility toggle, and `compact` mode are not implemented; they are tracked as enhancement backlog.
- While a value is actively typed, the component accepts intermediate states and snaps back to a valid number on blur / Enter.
- The clear button only appears on hover or focus (desktop convention).

## FAQ

### How do I restrict the input to a numeric range?

Pass `min` and `max`. Values are clamped on change, and the increment/decrement buttons are disabled at the boundaries.

### How do I control the number of decimal places?

Control the number of decimal places via `formatOptions.maximumFractionDigits` (for example `{ maximumFractionDigits: 2 }`). Formatting and step calculation respect the configured precision.

### How does keyboard entry work?

Arrow Up/Down step by `step`; Page Up/Down step by `step * 10`; Home/End jump to `min`/`max`; Enter commits; the mouse wheel adjusts the value when hovered.

### How do I localize the displayed number?

The component uses `Intl.NumberFormat` with the active locale (and any `formatOptions`). Thousands separators and decimal marks follow the locale automatically.

## InputOtp

- Page URL: /components/input-otp
- Markdown URL: /components/input-otp.md
- Description: A one-time-password (OTP / verification code) input built around a real native input. It keeps the robust selection, paste, and mobile autofill behavior of vue-input-otp while exposing a default SoybeanUI presentation and a fully custom scoped slot. Use it for SMS codes, email verification codes, two-factor authentication, or any fixed-length code entry.

# InputOtp

## Overview

A one-time-password (OTP / verification code) input built around a real native input. It keeps the robust selection, paste, and mobile autofill behavior of vue-input-otp while exposing a default SoybeanUI presentation and a fully custom scoped slot. Use it for SMS codes, email verification codes, two-factor authentication, or any fixed-length code entry.

## Usage

Usage examples for input-otp are rendered on the site.

## Features

- 📏 6 sizes: xs, sm, md, lg, xl, 2xl
- 🔤 Real native input overlay — native selection, paste, and mobile autofill / password-manager behavior
- 📐 `align` control: start / center / end
- 🎨 Fully custom `default` slot per character, with placeholder chars and fake caret
- 🔢 `maxlength` clamping plus `pattern` validation (double-layer `beforeinput` + rollback)
- 📋 `pasteTransformer` for normalizing pasted input, and a `complete` event when full
- 🔐 Password-manager badge detection (disable via `pushPasswordManagerStrategy`)
- ♿ Full accessibility support — `aria-label`, `inputmode`, axe-clean

## Demos

Interactive demos for input-otp are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): InputOtp, InputOtpCompact, InputOtpInput, InputOtpPositioner, InputOtpRoot.

### InputOtp

#### Props
Properties for the InputOtp component.
- `class`: Root class. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `align`: Align. (type `Align`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<InputOtpUi>`; optional)
- `id`: The id of the native input element. (type `string`; optional)
- `autocomplete`: Autocomplete hint passed to the native input. (type `string`; optional)
- `autofocus`: Whether the input should be focused on mount. (type `boolean`; optional)
- `disabled`: Whether the input is disabled. (type `boolean`; optional)
- `minlength`: Minimum length forwarded to the native input. (type `number`; optional)
- `placeholder`: Placeholder characters used by the visual slots. (type `string`; optional)
- `readonly`: Whether the input is readonly. (type `boolean`; optional)
- `ariaLabel`: Accessible label forwarded to the native input. (type `string`; optional)
- `modelValue`: The controlled value of the OTP input. (type `string`; optional)
- `defaultValue`: The uncontrolled default value of the OTP input. (type `string`; optional)
- `maxlength`: The number of OTP slots. (type `number`; required)
- `inputmode`: Virtual keyboard mode for mobile devices. (type `InputOtpInputMode`; optional)
- `pattern`: Pattern used to validate the whole OTP value. (type `string | RegExp`; optional)
- `pushPasswordManagerStrategy`: Strategy used to avoid overlapping password manager badges. (type `InputOtpPushPasswordManagerStrategy`; optional)
- `pasteTransformer`: Transform pasted content before it is inserted. (type `((pasted: string) => string)`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the InputOtp component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `complete`: Emitted when complete occurs. (type `[value: string]`; parameters `value: string`)
- `input`: Emitted when input occurs. (type `[value: string]`; parameters `value: string`)
- `change`: Emitted when change occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[event: Event]`; parameters `event: Event`)
- `focus`: Emitted when focus occurs. (type `[event: FocusEvent]`; parameters `event: FocusEvent`)
- `blur`: Emitted when blur occurs. (type `[event: FocusEvent]`; parameters `event: FocusEvent`)
- `mouseover`: Emitted when mouseover occurs. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `mouseleave`: Emitted when mouseleave occurs. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `paste`: Emitted when paste occurs. (type `[event: ClipboardEvent]`; parameters `event: ClipboardEvent`)
#### Slots
Slots for the InputOtp component.
- `default`: Custom content for the default slot. (type `((props: InputOtpRootSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the InputOtp component.
- `char`: The typed character at the current slot. (type `string | null`; required)
- `placeholderChar`: Placeholder character rendered when the slot is empty. (type `string | null`; required)
- `isActive`: Whether the slot is covered by the current selection or caret. (type `boolean`; required)
- `hasFakeCaret`: Whether the slot should render a fake caret. (type `boolean`; required)

### InputOtpCompact

#### Props
Properties for the InputOtpCompact component.
- `id`: The id of the native input element. (type `string`; optional)
- `autocomplete`: Autocomplete hint passed to the native input. (type `string`; optional)
- `autofocus`: Whether the input should be focused on mount. (type `boolean`; optional)
- `disabled`: Whether the input is disabled. (type `boolean`; optional)
- `minlength`: Minimum length forwarded to the native input. (type `number`; optional)
- `placeholder`: Placeholder characters used by the visual slots. (type `string`; optional)
- `readonly`: Whether the input is readonly. (type `boolean`; optional)
- `ariaLabel`: Accessible label forwarded to the native input. (type `string`; optional)
- `modelValue`: The controlled value of the OTP input. (type `string`; optional)
- `defaultValue`: The uncontrolled default value of the OTP input. (type `string`; optional)
- `maxlength`: The number of OTP slots. (type `number`; required)
- `inputmode`: Virtual keyboard mode for mobile devices. (type `InputOtpInputMode`; optional)
- `pattern`: Pattern used to validate the whole OTP value. (type `string | RegExp`; optional)
- `pushPasswordManagerStrategy`: Strategy used to avoid overlapping password manager badges. (type `InputOtpPushPasswordManagerStrategy`; optional)
- `pasteTransformer`: Transform pasted content before it is inserted. (type `((pasted: string) => string)`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the InputOtpCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `complete`: Emitted when complete occurs. (type `[value: string]`; parameters `value: string`)
- `input`: Emitted when input occurs. (type `[value: string]`; parameters `value: string`)
- `change`: Emitted when change occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[event: Event]`; parameters `event: Event`)
- `focus`: Emitted when focus occurs. (type `[event: FocusEvent]`; parameters `event: FocusEvent`)
- `blur`: Emitted when blur occurs. (type `[event: FocusEvent]`; parameters `event: FocusEvent`)
- `mouseover`: Emitted when mouseover occurs. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `mouseleave`: Emitted when mouseleave occurs. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `paste`: Emitted when paste occurs. (type `[event: ClipboardEvent]`; parameters `event: ClipboardEvent`)
#### Slots
Slots for the InputOtpCompact component.
- `default`: Custom content for the default slot. (type `((props: InputOtpRootSlotProps) => any) | undefined`)

### InputOtpInput

- No documented props, emits, slots, or slot props were available.

### InputOtpPositioner

- No documented props, emits, slots, or slot props were available.

### InputOtpRoot

#### Props
Properties for the InputOtpRoot component.
- `id`: The id of the native input element. (type `string`; optional)
- `autocomplete`: Autocomplete hint passed to the native input. (type `string`; optional)
- `autofocus`: Whether the input should be focused on mount. (type `boolean`; optional)
- `disabled`: Whether the input is disabled. (type `boolean`; optional)
- `minlength`: Minimum length forwarded to the native input. (type `number`; optional)
- `placeholder`: Placeholder characters used by the visual slots. (type `string`; optional)
- `readonly`: Whether the input is readonly. (type `boolean`; optional)
- `ariaLabel`: Accessible label forwarded to the native input. (type `string`; optional)
- `modelValue`: The controlled value of the OTP input. (type `string`; optional)
- `defaultValue`: The uncontrolled default value of the OTP input. (type `string`; optional)
- `maxlength`: The number of OTP slots. (type `number`; required)
- `inputmode`: Virtual keyboard mode for mobile devices. (type `InputOtpInputMode`; optional)
- `pattern`: Pattern used to validate the whole OTP value. (type `string | RegExp`; optional)
- `pushPasswordManagerStrategy`: Strategy used to avoid overlapping password manager badges. (type `InputOtpPushPasswordManagerStrategy`; optional)
- `pasteTransformer`: Transform pasted content before it is inserted. (type `((pasted: string) => string)`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the InputOtpRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `complete`: Emitted when complete occurs. (type `[value: string]`; parameters `value: string`)
- `input`: Emitted when input occurs. (type `[value: string]`; parameters `value: string`)
- `change`: Emitted when change occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[event: Event]`; parameters `event: Event`)
- `focus`: Emitted when focus occurs. (type `[event: FocusEvent]`; parameters `event: FocusEvent`)
- `blur`: Emitted when blur occurs. (type `[event: FocusEvent]`; parameters `event: FocusEvent`)
- `mouseover`: Emitted when mouseover occurs. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `mouseleave`: Emitted when mouseleave occurs. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `paste`: Emitted when paste occurs. (type `[event: ClipboardEvent]`; parameters `event: ClipboardEvent`)
#### Slot Props
Slot properties for the InputOtpRoot component.
- `slots`: Slots exposed in the slot scope. (type `InputOtpSlotProps[]`; required)
- `isFocused`: Whether the item is focused. (type `boolean`; required)
- `isHovering`: Whether the item is hovered. (type `boolean`; required)

## Notes

### Architecture and benchmark differences

SoybeanUI splits input-otp into a headless layer (`@soybeanjs/headless/input-otp`) that owns the transparent input overlay, selection mirroring, and validation, and a styled layer (`@soybeanjs/ui`) that owns variants and UnoCSS classes. The headless `InputOtpCompact` composes `InputOtpRoot` / `InputOtpPositioner` / `InputOtpInput`. This is a port of the vue-input-otp approach used by reka-ui and shadcn, with SoybeanUI's size variants and `align` states as differentiators.

| Capability                      | SoybeanUI | reka-ui `InputOtp` | shadcn `InputOTP` | Element Plus |
| :------------------------------ | :-------: | :----------------: | :---------------: | :----------: |
| headless/styled split           |    ✅     |         —          |         —         |      —       |
| Controlled / uncontrolled       |    ✅     |         ✅         |        ✅         |      —       |
| `maxlength` / `pattern`         |    ✅     |         ✅         |        ✅         |      —       |
| Real input transparent overlay  |    ✅     |         ✅         |        ✅         |      —       |
| Selection mirroring             |    ✅     |         ✅         |        ✅         |      —       |
| Paste transformer               |    ✅     |         ✅         |        ✅         |      —       |
| Password-manager badge handling |    ✅     |         ✅         |        ✅         |      —       |
| iOS autofill                    |    ✅     |         ✅         |        ✅         |      —       |
| `complete` event                |    ✅     |         ✅         |        ✅         |      —       |
| Size variants (xs…2xl)          |    ✅     |         —          |         —         |      —       |
| `align` states                  |    ✅     |         ✅         |        ✅         |      —       |
| Custom visual slot (fake caret) |    ✅     |         ✅         |        ✅         |      —       |

### Cautions

- `maxlength` is required — it drives the number of rendered characters.
- The `aria-label` prop is declared as `ariaLabel` (camelCase); both kebab-case attributes and camelCase props work, and it falls back to the localized default `One-time password`.
- Locale-aware default `aria-label` and `contextmenu` handling are tracked as enhancement backlog.

## FAQ

### How do I customize the character cells?

Use the `default` slot. Each character receives `char`, `placeholderChar`, `isActive`, and `hasFakeCaret` so you can render boxes, separators, or custom carets.

### How do I trigger an action when the code is complete?

Listen for the `complete` event, emitted once all cells are filled.

### How do I restrict what characters can be entered?

Pass `maxlength` for length and `pattern` for a per-character validation regex. Invalid input is rejected by `beforeinput` interception and rolled back on `input`.

### How do I make the OTP usable in a native form?

Pass `name` — the transparent input carries the value and participates in native form submission and autofill.

## Kbd

- Page URL: /components/kbd
- Markdown URL: /components/kbd.md
- Description: The SKbd component represents a keyboard input element, typically used to display keyboard shortcuts and key combinations. It wraps the native <kbd> element and optionally symbolizes key names (e.g., shift → ⇧, enter → ↵) with platform-aware resolution for modifier keys (meta, alt, ctrl).

# Kbd

## Overview

The `SKbd` component represents a keyboard input element, typically used to display keyboard shortcuts and key combinations. It wraps the native `<kbd>` element and optionally symbolizes key names (e.g., `shift` → `⇧`, `enter` → `↵`) with platform-aware resolution for modifier keys (`meta`, `alt`, `ctrl`).

Use it in tooltips, help dialogs, or inline documentation to show shortcuts like `⌘K` or `Ctrl+S`.

## Usage

Usage examples for kbd are rendered on the site.

## Features

- ⌨️ **Symbolization** — Converts known key names (`shift`, `enter`, `tab`, arrows, etc.) to their Unicode symbols automatically.
- 🖥️ **Platform-aware modifiers** — `meta`, `alt`, and `ctrl` resolve to the correct symbol for the user's OS (`⌘`/`⌥`/`⌃` on macOS, `⊞`/`alt`/`ctrl` on Windows).
- 🎨 **Variants** — `solid`, `outline` (default), and `ghost` visual styles.
- 📐 **Size scaling** — Six sizes (`xs`–`2xl`) control height, min-width, and font size.
- 🌡️ **Raised effect** — Optional `raised` prop adds a 2px shadow for a tactile, key-cap appearance.
- 🔗 **Key groups** — When `value` is an array, a `data-group` attribute enables letter-spacing for readability.
- ♿ **Semantic** — Uses the native `<kbd>` element, which is inherently accessible to screen readers.
- 🌐 **Dark mode** — Uses semantic color tokens that adapt to dark themes automatically.

## Demos

Interactive demos for kbd are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Kbd.

### Kbd

#### Props
Properties for the Kbd component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `KbdVariant`; optional)
- `raised`: Whether raised. (type `boolean`; optional)
- `value`: The value of the component. (type `KbdValue | KbdValue[]`; optional)
- `symbolize`: Whether to convert the command value to symbol representation. (type `boolean`; default `true`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits `Kbd` into a headless layer (`@soybeanjs/headless/kbd`) that owns the `<kbd>` element, symbolization logic (via the `useKbd` composable), and `data-group` state, and a styled layer (`@soybeanjs/ui`) that owns the `cv()` variant recipe (size/variant/raised). This follows the shadcn/ui headless/styled separation. The `useKbd` composable is a `createSharedComposable` singleton that detects macOS via `navigator.userAgent`.

| Aspect         | SoybeanUI                                                      | shadcn/ui `Kbd` | Mantine `Kbd` | Ant Design |
| :------------- | :------------------------------------------------------------- | :-------------- | :------------ | :--------- |
| Architecture   | headless + styled split                                        | styled only     | styled only   | —          |
| Symbolization  | `useKbd` composable; 20 key symbols + platform-aware modifiers | —               | —             | —          |
| Platform-aware | macOS / Windows modifier resolution via `navigator.userAgent`  | —               | —             | —          |
| Variants       | `solid` / `outline` / `ghost`                                  | —               | —             | —          |
| Size scaling   | `xs`–`2xl`                                                     | `sm`–`lg`       | `xs`–`xl`     | —          |
| Raised effect  | `raised` prop (2px shadow)                                     | —               | —             | —          |
| Key groups     | `data-group` + letter-spacing                                  | —               | —             | —          |

### Runtime cautions

- **Platform detection**: `useKbd` detects macOS via `navigator.userAgent` inside `onMounted`. On SSR, modifier keys (`meta`, `alt`, `ctrl`) render a space placeholder and update to the correct symbol after client hydration. This may produce a hydration mismatch warning for modifier keys; Vue resolves it on mount. Non-modifier keys (e.g., `shift` → `⇧`, `enter` → `↵`) are static and SSR-safe.
- **Case sensitivity**: Known key names in `KbdKey` are lowercase (`shift`, `enter`, `tab`). Passing a capitalized string like `Shift` will not match the symbol map and will fall back to `SHIFT` (uppercased). Always use lowercase key names for symbolization.
- **Singleton composable**: `useKbd` is a `createSharedComposable` — the platform detection runs once and is shared across all `SKbd` instances. This avoids repeated `navigator` checks.

### FAQ

**How do I display a key combination like `Ctrl+K`?**
Pass an array: `<SKbd :value="['ctrl', 'K']" />`. The component joins the symbolized values and adds `data-group` for letter-spacing. On macOS, `ctrl` resolves to `⌃` and the output is `⌃K`.

**How do I disable symbolization?**
Set `symbolize` to `false`: `<SKbd value="shift" :symbolize="false" />` renders the raw text `shift` instead of `⇧`.

**Why does my modifier key show a space on the server?**
`meta`, `alt`, and `ctrl` require platform detection (`navigator.userAgent`), which only runs in the browser. On SSR they render a space placeholder and update to the correct symbol (`⌘`, `⌥`, `⌃`) after hydration. Use non-modifier keys or accept the hydration update for modifier-based shortcuts.

**How do I customize the content entirely?**
Use the default slot: `<SKbd><span class="my-style">⌘P</span></SKbd>`. The slot replaces the `value` prop entirely.

## Label

- Page URL: /components/label
- Markdown URL: /components/label.md
- Description: The SLabel component renders a native <label> element that provides an accessible caption for form controls. Use the for prop to associate the label with an input by its id — clicking the label then focuses the associated control. The component prevents text selection on double-click for a cleaner UX and supports size scaling via the design system.

# Label

## Overview

The `SLabel` component renders a native `<label>` element that provides an accessible caption for form controls. Use the `for` prop to associate the label with an input by its `id` — clicking the label then focuses the associated control. The component prevents text selection on double-click for a cleaner UX and supports size scaling via the design system.

## Usage

Usage examples for label are rendered on the site.

## Features

- 🏷️ **Native `<label>`** — Uses the semantically correct HTML element for form labels.
- 🔗 **`for` association** — Pass `for="input-id"` to link the label to a form control; clicking the label focuses it.
- 📐 **Size scaling** — Six sizes (`xs`–`2xl`) control label typography.
- 🖱️ **Selection prevention** — Double-clicking the label won't select its text, avoiding accidental text selection when interacting with the associated input.
- ♿ **Accessible** — Native `<label>` is inherently accessible; `peer-disabled` styles dim the label when the associated control is disabled.
- 🎨 **Class override** — `class` prop for custom styling on top of variant defaults.

## Demos

Interactive demos for label are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Label.

### Label

#### Props
Properties for the Label component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `for`: The id of the element the label is associated with. (type `string`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits `Label` into a headless layer (`@soybeanjs/headless/label`) that owns the `<label>` element, `for` association, and double-click text-selection prevention, and a styled layer (`@soybeanjs/ui`) that owns the `cv()` variant recipe (size). This follows the shadcn/ui headless/styled separation, which itself derives from Radix UI's Label primitive.

| Aspect               | SoybeanUI                     | shadcn/ui `Label` | Ant Design `Form.Label` | Element Plus `FormLabel` | MUI `InputLabel` |
| :------------------- | :---------------------------- | :---------------- | :---------------------- | :----------------------- | :--------------- |
| Architecture         | headless + styled split       | headless + styled | form-coupled            | form-coupled             | styled only      |
| Native `<label>`     | ✅                            | ✅                | ✅ (within Form)        | ✅ (within Form)         | ✅               |
| `for` association    | ✅ standalone                 | ✅ standalone     | auto via Form           | auto via Form            | auto via Form    |
| Size scaling         | `xs`–`2xl`                    | —                 | —                       | —                        | `size`           |
| Selection prevention | ✅ `mousedown` + `detail > 1` | ✅                | —                       | —                        | —                |
| Disabled peer style  | `peer-disabled:opacity-50`    | ✅                | —                       | —                        | —                |

### Runtime cautions

- **Standalone usage**: Unlike Ant Design and Element Plus where labels are coupled to `<Form>`, `SLabel` works standalone — pass `for="input-id"` to associate it with any input. This matches the shadcn/ui pattern.
- **Disabled state**: The label uses `peer-disabled:opacity-50` to visually dim when the sibling input is disabled. For this to work, the input must be a sibling element with the `peer` class and a `disabled` attribute.
- **Double-click**: The `mousedown` handler calls `event.preventDefault()` when `event.detail > 1` (double-click). This prevents text selection but does not interfere with single clicks or label-to-input focus behavior.

### FAQ

**How do I associate a label with an input?**
Pass the input's `id` to the label's `for` prop: `<SLabel for="email">Email</SLabel>` then `<SInput id="email" />`. Clicking the label will focus the input.

**Can I use `SLabel` inside a form without `for`?**
Yes. If you wrap the input inside the label (`<SLabel>Email <SInput /></SLabel>`), the browser auto-associates them. The `for` prop is only needed when the label and input are siblings.

**Why does the label dim when the input is disabled?**
The base class includes `peer-disabled:opacity-50`. When the sibling input (with `peer` class) is disabled, the label opacity drops to 50%. This is a UX convention from shadcn/ui.

**How do I prevent the double-click selection prevention?**
The selection prevention is built into the headless layer. If you need standard text selection behavior, use the headless `Label` directly and omit the `@mousedown` handler, or override it in your own wrapper.

## Layout

- Page URL: /components/layout
- Markdown URL: /components/layout.md
- Description: The layout component structure for admin dashboards or complex applications. It manages sidebar, header, footer, tabs, and main content areas.

# Layout

## Overview

The layout component structure for admin dashboards or complex applications. It manages sidebar, header, footer, tabs, and main content areas.

## Features

- **One unified layout** — `SLayout` combines the modern sidebar shell with admin-classic capabilities: scrollable wrapper, fixed header/footer, and orientation support.
- **Three variants** — `sidebar` (bordered), `floating` (rounded shadow), and `inset` (content with margin and rounded corners).
- **Collapsible sidebar** — `collapsible="icon"` collapses the sidebar to a rail width; `collapsible="offcanvas"` slides it off-canvas while preserving layout space.
- **Side control** — `side="left"` or `side="right"` flips the sidebar position with full RTL-aware logical properties.
- **Mobile drawer** — unset `isMobile` follows the viewport and swaps the desktop sidebar for a `Dialog`-based drawer with overlay and focus trap; pass a boolean to override the breakpoint.
- **Slot-level overrides** — every region (sidebar, header, tab, content, footer) accepts per-slot `*Props` for granular attribute forwarding.
- **CSS-variable driven** — dimensions (`sidebarWidth`, `headerHeight`, `tabHeight`, `footerHeight`) emit rem-based CSS variables for runtime customization.
- **Size scaling** — `size` (xs…2xl) scales the layout spacing and base typography through `themeSizeRatio`.
- **`fullContent` mode** — pins the content area to fill the viewport while keeping the tab bar above it.
- **Orientation** — `Layout` supports horizontal (sidebar beside content) and vertical (sidebar stacked under header) orientations.
- **Scroll behaviors** — `scrollBehavior="content"` scrolls only the content region; `scrollBehavior="wrapper"` scrolls the entire main wrapper.
- **Fixed header/footer** — `fixedTop` and `fixedFooter` keep the header/footer pinned during content scroll, with automatic placeholder elements to prevent overlap.
- **Base z-index control** — `baseZIndex` derives the stacking order of sidebar, header, tab, and footer so multiple layouts compose predictably.
- **Headless composition** — every region (`LayoutRoot`, `LayoutSidebar`, `LayoutRail`, `LayoutHeader`, `LayoutTab`, `LayoutContent`, `LayoutFooter`, `LayoutMobile`, `LayoutTrigger`) is exported from `@soybeanjs/headless/layout` for custom styled builds.
- **SSR safe** — no `window`/`document` access in setup; the viewport fallback is guarded, and `useId()` generates stable scroll ids for server rendering.

## Usage

Usage examples for layout are rendered on the site.

## Demos

Interactive demos for layout are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (13): Layout, LayoutCompact, LayoutContent, LayoutFooter, LayoutHeader, LayoutMain, LayoutMobile, LayoutPlaceholder, LayoutRail, LayoutRoot, LayoutSidebar, LayoutTab, LayoutTrigger.

### Layout

#### Props
Properties for the Layout component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<LayoutUi>`; optional)
- `open`: The controlled open state of the layout. Can be bound with `v-model`. (type `boolean`; optional)
- `defaultOpen`: The open state of the layout when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `side`: The side of the layout. (type `HorizontalSide`; optional)
- `variant`: The variant of the layout. (type `LayoutVariant`; optional)
- `collapsible`: The collapsible state of the layout. (type `LayoutCollapsible`; optional)
- `sidebarVisible`: whether to show the sidebar. (type `boolean`; default `true`; optional)
- `sidebarWidth`: The width of the sidebar. (px) (type `number`; default `240`; optional)
- `collapsedSidebarWidth`: The width of the sidebar when it is collapsed. (px) (type `number`; default `50`; optional)
- `isMobile`: Whether the layout is in mobile view. Resolution order: this prop, then a host viewport decision provided through `provideViewportContext` (a simulated viewport — a device frame, an embedded shell), then `useMediaQuery(mobileViewportQuery)` — the same breakpoint the styled desktop sidebar is hidden at. Pass an explicit boolean to force the mode (e.g. a server-side detection); `false` re-enables the inline sidebar even below the breakpoint. (type `boolean`; optional)
- `mobileOpen`: The controlled open state of the mobile drawer. Can be bound with `v-model:mobileOpen`. Kept apart from `open`, which drives the desktop sidebar: on mobile the inline sidebar is replaced by a drawer, so the two states never apply at the same time. (type `boolean`; optional)
- `defaultMobileOpen`: The open state of the mobile drawer when it is initially rendered. (type `boolean`; default `false`; optional)
- `mobileSidebarWidth`: The width of the sidebar in the mobile view. (px) (type `number`; default `240`; optional)
- `headerVisible`: whether to show the header. (type `boolean`; default `true`; optional)
- `headerHeight`: The height of the header. (px) (type `number`; default `56`; optional)
- `tabVisible`: whether to show the tab. (type `boolean`; default `true`; optional)
- `tabHeight`: The height of the tab. (px) (type `number`; default `44`; optional)
- `footerVisible`: whether to show the footer. (type `boolean`; default `true`; optional)
- `footerHeight`: The height of the footer. (px) (type `number`; default `48`; optional)
- `fullContent`: whether the content takes the full height of the layout (include). (type `boolean`; default `false`; optional)
- `pxToRem`: The function to convert pixels to rem. (type `((px: number) => number)`; default `(px: number) => px / 16 (16 is the base font size)`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `scrollBehavior`: Scroll behavior. (type `LayoutScrollBehavior`; optional)
- `scrollId`: Scroll id. (type `string`; optional)
- `baseZIndex`: The base z-index of the layout. The z-index of the sidebar, header, tab, footer, and their fixed versions will be calculated based on this value. (type `number`; default `50`; optional)
- `fixedTop`: Whether the header and tab are fixed to the top of the layout when the orientation is vertical. If true, the header and tab will be fixed to the top of the layout when the orientation is vertical, and will scroll with the content when the orientation is horizontal. (type `boolean`; default `true`; optional)
- `fixedFooter`: Whether footer is fixed (type `boolean`; default `true`; optional)
- `stretchFooter`: Whether the footer should stretch to the full width of the layout or the content when layout orientation is vertical. (type `boolean`; default `true`; optional)
- `sidebarProps`: No description. (type `LayoutSidebarProps`; optional)
- `railProps`: No description. (type `LayoutRailProps`; optional)
- `mainProps`: No description. (type `LayoutMainProps`; optional)
- `headerProps`: No description. (type `LayoutHeaderProps`; optional)
- `tabProps`: No description. (type `LayoutTabProps`; optional)
- `contentProps`: No description. (type `LayoutContentProps`; optional)
- `footerProps`: No description. (type `LayoutFooterProps`; optional)
- `mobileProps`: No description. (type `LayoutMobileProps`; optional)
#### Emits
Events for the Layout component.
- `update:open`: Emitted when the open state changes. (type `[open: boolean]`; parameters `open: boolean`)
- `update:mobileOpen`: Emitted when the mobile drawer open state changes. (type `[open: boolean]`; parameters `open: boolean`)
#### Slots
Slots for the Layout component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `sidebar`: Custom content for the sidebar slot. `collapsed` is the mode-aware state to render from: it is `false` on mobile, where the sidebar is a drawer that always shows the expanded navigation, so a collapse chosen on desktop does not follow the content into the drawer. `open` still reports the desktop state. (type `((props: { open: boolean | undefined; collapsedSidebarWidth: number; collapsed: boolean; }) => any) | undefined`)
- `header`: Custom content for the header slot. (type `(() => any) | undefined`)
- `tab`: Custom content for the tab slot. (type `(() => any) | undefined`)
- `content`: Custom content for the content slot. (type `(() => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `(() => any) | undefined`)

### LayoutCompact

#### Props
Properties for the LayoutCompact component.
- `open`: The controlled open state of the layout. Can be bound with `v-model`. (type `boolean`; optional)
- `defaultOpen`: The open state of the layout when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `side`: The side of the layout. (type `HorizontalSide`; optional)
- `variant`: The variant of the layout. (type `LayoutVariant`; optional)
- `collapsible`: The collapsible state of the layout. (type `LayoutCollapsible`; optional)
- `sidebarVisible`: whether to show the sidebar. (type `boolean`; default `true`; optional)
- `sidebarWidth`: The width of the sidebar. (px) (type `number`; default `240`; optional)
- `collapsedSidebarWidth`: The width of the sidebar when it is collapsed. (px) (type `number`; default `50`; optional)
- `isMobile`: Whether the layout is in mobile view. Resolution order: this prop, then a host viewport decision provided through `provideViewportContext` (a simulated viewport — a device frame, an embedded shell), then `useMediaQuery(mobileViewportQuery)` — the same breakpoint the styled desktop sidebar is hidden at. Pass an explicit boolean to force the mode (e.g. a server-side detection); `false` re-enables the inline sidebar even below the breakpoint. (type `boolean`; optional)
- `mobileOpen`: The controlled open state of the mobile drawer. Can be bound with `v-model:mobileOpen`. Kept apart from `open`, which drives the desktop sidebar: on mobile the inline sidebar is replaced by a drawer, so the two states never apply at the same time. (type `boolean`; optional)
- `defaultMobileOpen`: The open state of the mobile drawer when it is initially rendered. (type `boolean`; default `false`; optional)
- `mobileSidebarWidth`: The width of the sidebar in the mobile view. (px) (type `number`; default `240`; optional)
- `headerVisible`: whether to show the header. (type `boolean`; default `true`; optional)
- `headerHeight`: The height of the header. (px) (type `number`; default `56`; optional)
- `tabVisible`: whether to show the tab. (type `boolean`; default `true`; optional)
- `tabHeight`: The height of the tab. (px) (type `number`; default `44`; optional)
- `footerVisible`: whether to show the footer. (type `boolean`; default `true`; optional)
- `footerHeight`: The height of the footer. (px) (type `number`; default `48`; optional)
- `fullContent`: whether the content takes the full height of the layout (include). (type `boolean`; default `false`; optional)
- `pxToRem`: The function to convert pixels to rem. (type `((px: number) => number)`; default `(px: number) => px / 16 (16 is the base font size)`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `scrollBehavior`: Scroll behavior. (type `LayoutScrollBehavior`; optional)
- `scrollId`: Scroll id. (type `string`; optional)
- `baseZIndex`: The base z-index of the layout. The z-index of the sidebar, header, tab, footer, and their fixed versions will be calculated based on this value. (type `number`; default `50`; optional)
- `fixedTop`: Whether the header and tab are fixed to the top of the layout when the orientation is vertical. If true, the header and tab will be fixed to the top of the layout when the orientation is vertical, and will scroll with the content when the orientation is horizontal. (type `boolean`; default `true`; optional)
- `fixedFooter`: Whether footer is fixed (type `boolean`; default `true`; optional)
- `stretchFooter`: Whether the footer should stretch to the full width of the layout or the content when layout orientation is vertical. (type `boolean`; default `true`; optional)
- `sidebarProps`: No description. (type `LayoutSidebarProps`; optional)
- `railProps`: No description. (type `LayoutRailProps`; optional)
- `mainProps`: No description. (type `LayoutMainProps`; optional)
- `headerProps`: No description. (type `LayoutHeaderProps`; optional)
- `tabProps`: No description. (type `LayoutTabProps`; optional)
- `contentProps`: No description. (type `LayoutContentProps`; optional)
- `footerProps`: No description. (type `LayoutFooterProps`; optional)
- `mobileProps`: No description. (type `LayoutMobileProps`; optional)
#### Emits
Events for the LayoutCompact component.
- `update:open`: Emitted when the open state changes. (type `[open: boolean]`; parameters `open: boolean`)
- `update:mobileOpen`: Emitted when the mobile drawer open state changes. (type `[open: boolean]`; parameters `open: boolean`)
#### Slots
Slots for the LayoutCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `sidebar`: Custom content for the sidebar slot. `collapsed` is the mode-aware state to render from: it is `false` on mobile, where the sidebar is a drawer that always shows the expanded navigation, so a collapse chosen on desktop does not follow the content into the drawer. `open` still reports the desktop state. (type `((props: { open: boolean | undefined; collapsedSidebarWidth: number; collapsed: boolean; }) => any) | undefined`)
- `header`: Custom content for the header slot. (type `(() => any) | undefined`)
- `tab`: Custom content for the tab slot. (type `(() => any) | undefined`)
- `content`: Custom content for the content slot. (type `(() => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `(() => any) | undefined`)

### LayoutContent

- No documented props, emits, slots, or slot props were available.

### LayoutFooter

- No documented props, emits, slots, or slot props were available.

### LayoutHeader

- No documented props, emits, slots, or slot props were available.

### LayoutMain

- No documented props, emits, slots, or slot props were available.

### LayoutMobile

- No documented props, emits, slots, or slot props were available.

### LayoutPlaceholder

#### Props
Properties for the LayoutPlaceholder component.
- `type`: Which region the placeholder reserves space for. (type `'header' | 'tab' | 'footer'`; required)

### LayoutRail

- No documented props, emits, slots, or slot props were available.

### LayoutRoot

#### Props
Properties for the LayoutRoot component.
- `open`: The controlled open state of the layout. Can be bound with `v-model`. (type `boolean`; optional)
- `defaultOpen`: The open state of the layout when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `side`: The side of the layout. (type `HorizontalSide`; optional)
- `variant`: The variant of the layout. (type `LayoutVariant`; optional)
- `collapsible`: The collapsible state of the layout. (type `LayoutCollapsible`; optional)
- `sidebarVisible`: whether to show the sidebar. (type `boolean`; default `true`; optional)
- `sidebarWidth`: The width of the sidebar. (px) (type `number`; default `240`; optional)
- `collapsedSidebarWidth`: The width of the sidebar when it is collapsed. (px) (type `number`; default `50`; optional)
- `isMobile`: Whether the layout is in mobile view. Resolution order: this prop, then a host viewport decision provided through `provideViewportContext` (a simulated viewport — a device frame, an embedded shell), then `useMediaQuery(mobileViewportQuery)` — the same breakpoint the styled desktop sidebar is hidden at. Pass an explicit boolean to force the mode (e.g. a server-side detection); `false` re-enables the inline sidebar even below the breakpoint. (type `boolean`; optional)
- `mobileOpen`: The controlled open state of the mobile drawer. Can be bound with `v-model:mobileOpen`. Kept apart from `open`, which drives the desktop sidebar: on mobile the inline sidebar is replaced by a drawer, so the two states never apply at the same time. (type `boolean`; optional)
- `defaultMobileOpen`: The open state of the mobile drawer when it is initially rendered. (type `boolean`; default `false`; optional)
- `mobileSidebarWidth`: The width of the sidebar in the mobile view. (px) (type `number`; default `240`; optional)
- `headerVisible`: whether to show the header. (type `boolean`; default `true`; optional)
- `headerHeight`: The height of the header. (px) (type `number`; default `56`; optional)
- `tabVisible`: whether to show the tab. (type `boolean`; default `true`; optional)
- `tabHeight`: The height of the tab. (px) (type `number`; default `44`; optional)
- `footerVisible`: whether to show the footer. (type `boolean`; default `true`; optional)
- `footerHeight`: The height of the footer. (px) (type `number`; default `48`; optional)
- `fullContent`: whether the content takes the full height of the layout (include). (type `boolean`; default `false`; optional)
- `pxToRem`: The function to convert pixels to rem. (type `((px: number) => number)`; default `(px: number) => px / 16 (16 is the base font size)`; optional)
- `orientation`: Orientation of the component. (type `DataOrientation`; optional)
- `scrollBehavior`: Scroll behavior. (type `LayoutScrollBehavior`; optional)
- `scrollId`: Scroll id. (type `string`; optional)
- `baseZIndex`: The base z-index of the layout. The z-index of the sidebar, header, tab, footer, and their fixed versions will be calculated based on this value. (type `number`; default `50`; optional)
- `fixedTop`: Whether the header and tab are fixed to the top of the layout when the orientation is vertical. If true, the header and tab will be fixed to the top of the layout when the orientation is vertical, and will scroll with the content when the orientation is horizontal. (type `boolean`; default `true`; optional)
- `fixedFooter`: Whether footer is fixed (type `boolean`; default `true`; optional)
- `stretchFooter`: Whether the footer should stretch to the full width of the layout or the content when layout orientation is vertical. (type `boolean`; default `true`; optional)
#### Emits
Events for the LayoutRoot component.
- `update:open`: Emitted when the open state changes. (type `[open: boolean]`; parameters `open: boolean`)
- `update:mobileOpen`: Emitted when the mobile drawer open state changes. (type `[open: boolean]`; parameters `open: boolean`)

### LayoutSidebar

- No documented props, emits, slots, or slot props were available.

### LayoutTab

- No documented props, emits, slots, or slot props were available.

### LayoutTrigger

#### Props
Properties for the LayoutTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark comparison

| Concern                      | SoybeanUI                                                                                      | Ant Design `Layout`/`Header`/`Sider`/`Content`/`Footer` | Element Plus `ElContainer`/`ElHeader`/`ElAside`/`ElMain`/`ElFooter` |
| :--------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------ |
| Headless / styled separation | ✅ `@soybeanjs/headless/layout` ships logic + structure; `@soybeanjs/ui` ships `scv()` recipes | ❌ single styled package                                | ❌ single styled package                                            |
| Sidebar variants             | `sidebar` / `floating` / `inset`                                                               | `sider` only                                            | `aside` only                                                        |
| Collapsible modes            | `icon` (rail) + `offcanvas` (slide out)                                                        | `collapsible` + `collapsedWidth`                        | —                                                                   |
| Mobile drawer                | built-in `Dialog`-based drawer (follows the viewport)                                          | requires `Drawer` composition                           | requires `Drawer` composition                                       |
| Fixed header/footer          | `Layout` with `fixedTop` / `fixedFooter` + automatic placeholders                              | requires manual sticky CSS                              | requires manual sticky CSS                                          |
| Orientation                  | `Layout` `orientation="horizontal" \| "vertical"`                                              | —                                                       | —                                                                   |
| Scroll behavior              | `wrapper` / `content` on `Layout`                                                              | —                                                       | —                                                                   |
| CSS-variable dimensions      | `--soybean-sidebar-width`, `--soybean-layout-header-height`, etc.                              | inline width on `Sider`                                 | inline width on `Aside`                                             |
| RTL support                  | logical properties (`start-*`, `end-*`, `ps-*`, `pe-*`) + `rtl:` variants on rail              | —                                                       | —                                                                   |
| Z-index orchestration        | `baseZIndex` derives sidebar/header/tab/footer z-index                                         | manual                                                  | manual                                                              |
| Region visibility            | `sidebarVisible` / `headerVisible` / `tabVisible` / `footerVisible` props                      | remove the component                                    | remove the component                                                |

### Runtime considerations

1. **CSS variables are rem-based** — `sidebarWidth`, `collapsedSidebarWidth`, `headerHeight`, `tabHeight`, `footerHeight`, and `mobileSidebarWidth` are converted via `pxToRem` (default `px / 16`). Pass a custom `pxToRem` to align with a non-default root font size.
2. **`size` scales spacing and typography** — the UI wrapper multiplies pixel dimensions by `themeSizeRatio[size] / themeSizeMap.md`, so `size="xs"` shrinks both text and sidebar width proportionally.
3. **`isMobile` resolves through three levels** — the prop, then a viewport a host publishes with `provideViewportContext` (a documentation device frame, an embedded shell), then `useMediaQuery(mobileViewportQuery)`, the breakpoint shared with the styled sidebar's `lt-md` hiding rule (`767.9px`). The winning source is published as `data-mobile-source="explicit|viewport"`, and the styled `lt-md` fallback only applies to `viewport`: an explicit `isMobile="false"` below the breakpoint keeps the inline sidebar **and** its reserved width, instead of reserving space for a sidebar the CSS had hidden. The drawer is teleported out of the layout, so on mobile the sidebar reserves no space: the start gaps (`--soybean-layout-start-gap`, `--soybean-layout-header-start-gap`, `--soybean-layout-footer-start-gap`) collapse to `0`, and each variant falls back to its own end gap — `sidebar`/`floating` become full-bleed, `inset` stays inset symmetrically on both edges. The same fallback covers `sidebarVisible="false"` on desktop: a hidden sidebar reserves no space either, so the extra spacing `floating`/`inset` add beside the sidebar width is withdrawn with it, and the main column stays aligned with the fixed header and footer. A host that resolves the sidebar to no column at all — `SAppShell`'s split modes do, while a first-level leaf is active — declares `sidebarWidth="0"` instead: the root then reports `data-sidebar-flow="false"`, the styled layer withdraws the same spacing and paints no column, and because the region itself stays mounted (its mount targets host teleported panes), only the column disappears, not the subtree.
4. **The `sidebar` slot renders from a mode-aware `collapsed`** — the slot hands its content `collapsed` next to `open`: it is `false` on mobile, where the sidebar is a drawer that always shows the expanded navigation, so a collapse picked on desktop does not follow the content into the drawer. Render from `collapsed` (a menu's `collapsed`, a brand title's visibility); `open` keeps reporting the desktop state, and the collapse returns the moment the mode does.
5. **`LayoutTrigger` vs `LayoutRail`** — `LayoutTrigger` is a focusable button in the header for keyboard users; `LayoutRail` is the edge drag affordance with `tabindex="-1"` (click-only). Both reflect `aria-expanded` for whichever sidebar the current mode renders — on mobile that is the drawer, not the desktop `open` state.
6. **`Layout` placeholder elements** — when `fixedTop` or `fixedFooter` is enabled, `LayoutPlaceholder` renders empty spacer divs (`data-soybean-layout-{header|tab|footer}-placeholder`) to prevent content from sliding under the fixed region. Hiding a region removes its placeholder with it, and the fixed regions below close the gap: with the header hidden the tab takes the layout's top edge instead of keeping the header's height (`inset` keeps only its own half-spacing).
7. **`scrollId` for scroll restoration** — `Layout` generates a stable `soybean-layout-scroll-{id}` on the scrolling element (wrapper or content depending on `scrollBehavior`). Pass `scrollId` to make it deterministic across SSR/CSR.

## FAQ

### Which layout mode should I use?

Use `SLayout` for both modern application shells and admin dashboards. It handles fixed header/footer, orientation switching (`horizontal` / `vertical`), and wrapper-level scrolling with placeholder spacers through a single unified component.

### How do I control the sidebar open state?

Use `v-model:open` (controlled) or `default-open` (uncontrolled). The state is reflected on the root via `data-state="expanded|collapsed"` and on `LayoutTrigger`/`LayoutRail` via `aria-expanded`.

On mobile the inline sidebar is replaced by a drawer, which carries its own state: bind `v-model:mobileOpen` (or `default-mobile-open` uncontrolled) to drive it. `open` keeps controlling the desktop sidebar, so a host that pins `isMobile` reaches what the user sees through `mobileOpen` — and the trigger reports that state. A single `open` binding cannot mean both, because the desktop sidebar defaults to expanded while the drawer has to start closed.

### How do I make the sidebar collapse to icons instead of sliding away?

Set `collapsible="icon"` (default) and `collapsedSidebarWidth` to the rail width. The sidebar shrinks to the collapsed width and the `sidebarGapHandler` adjusts the main area accordingly. Use `collapsible="offcanvas"` to slide the sidebar off-canvas instead.

### How does mobile mode work?

Leave `isMobile` unset (the default) and the layout follows the viewport, swapping the desktop sidebar for a `Dialog`-based drawer; pass a boolean to pin the mode yourself. The drawer inherits `mobileSidebarWidth` and reuses the same `sidebar` slot content. The drawer overlay and focus trap are provided by the underlying `Dialog` component.

### Can a host decide the mode for a whole subtree?

Yes. A host that already knows the answer — a device preview frame rendering a phone, a shell embedded in a desktop app, an SSR pass with a device hint — publishes it once with `provideViewportContext({ isMobile })` from `@soybeanjs/headless/composables`; every layout below it follows, and an explicit `isMobile` prop still wins per instance. Publishing at the frame rather than per component is also what keeps a documentation preview honest: the frame can simulate a phone viewport while the browser window stays wide. Note that viewport-prefixed utilities (`lt-md:hidden`, `sm:`, `md:`) still key off the browser window, so a simulated viewport moves the JS structure (drawer vs. inline sidebar) and the prop-driven spacing, not those breakpoint classes.

### Can I render the sidebar on the right?

Yes — set `side="right"`. The layout uses RTL-aware logical properties (`start-*`, `end-*`, `border-s`, `border-e`) so the sidebar, gap handler, rail cursor, and fixed header/footer insets all flip correctly.

### How are z-index values coordinated?

`Layout` accepts a `baseZIndex` (default `50`). The sidebar, header, tab, and footer z-index values are derived from this base so they stack predictably. The derived values are exposed as `--layout-{sidebar|header|tab|footer}-z-index` CSS variables.

### How do I customize region-level attributes?

Each region accepts a `*Props` prop on the compact component (e.g. `sidebarProps`, `headerProps`, `tabProps`, `contentProps`, `footerProps`, `mainProps`, `railProps`, `mobileProps`). These are forwarded to the corresponding headless region component.

## Link

- Page URL: /components/link
- Markdown URL: /components/link.md
- Description: SLink is a polymorphic link component that supports internal routing (via RouterLink) and external links (via <a> tag). It automatically detects external links and sets safe target and rel attributes, supports disabled state and polymorphic rendering (as/asChild).

# Link

## Overview

`SLink` is a polymorphic link component that supports internal routing (via `RouterLink`) and external links (via `<a>` tag). It automatically detects external links and sets safe `target` and `rel` attributes, supports disabled state and polymorphic rendering (`as`/`asChild`).

## Features

- 🔗 **Smart Routing**: Automatically distinguishes internal routes (`to`) from external links (`href`), gracefully falls back to `<a>` when RouterLink is unavailable.
- 🧩 **Pluggable Link Component**: Inject a framework-specific component (e.g. Nuxt `NuxtLink`) via `SConfigProvider` `linkComponent`.
- 🛡️ **Safe Defaults**: External links automatically get `target="_blank"` and `rel="noopener noreferrer"` to prevent reverse tabnabbing.
- 🔧 **Polymorphic**: Render as any element or component via `as`/`asChild`.
- ♿ **Accessible Disabled**: Disabled state sets `aria-disabled`, `role="link"`, `tabindex="-1"`, and blocks click events.
- 🎨 **Styling**: Override styles via `class` prop; `linkVariants` provides base utility classes.

## Usage

Usage examples for link are rendered on the site.

## Demos

Interactive demos for link are rendered on the site.

## Accessibility

- **Disabled state**: Sets `aria-disabled="true"`, `role="link"`, `tabindex="-1"`, and calls `preventDefault()` to block click navigation. Visually, the `data-disabled` attribute triggers `cursor-not-allowed` and `opacity-50`.
- **External link safety**: Automatically adds `rel="noopener noreferrer"` to prevent newly opened pages from accessing `window.opener`.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (3): Link, LinkBase, LinkExtra.

### Link

#### Props
Properties for the Link component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `replace`: Calls `router.replace` instead of `router.push`. (type `boolean`; optional)
- `href`: The URL the link should navigate to when clicked on. (type `string`; optional)
- `disabled`: When `true`, the link is disabled. (type `boolean`; optional)
- `activeClass`: Class to apply when the link is active (type `string`; optional)
- `exactActiveClass`: Class to apply when the link is exact active (type `string`; optional)
- `inactiveClass`: The class to apply to the link when it is inactive. (type `string`; optional)
- `prefetchedClass`: A class to apply to links that have been prefetched. (type `string`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `ariaCurrentValue`: Value passed to the attribute `aria-current` when the link is exact active. (type `'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location'`; default ``'page'``; optional)
- `viewTransition`: Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported. (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)
- `rel`: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links. (type `(string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null`; default `'noopener noreferrer'`; optional)
- `noRel`: If set to true, no rel attribute will be added to the link (type `boolean`; optional)
- `prefetch`: When enabled will prefetch middleware, layouts and payloads of links in the viewport. (type `boolean`; optional)
- `prefetchOn`: Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility. (type `'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }>`; optional)
- `noPrefetch`: Escape hatch to disable `prefetch` attribute. (type `boolean`; optional)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href` for this specific link. Overrides the global `trailingSlash` option if provided. (type `'append' | 'remove'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### LinkBase

#### Props
Properties for the LinkBase component.
- `href`: The URL the link should navigate to when clicked on. (type `string`; optional)
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)

### LinkExtra

#### Props
Properties for the LinkExtra component.
- `replace`: Calls `router.replace` instead of `router.push`. (type `boolean`; optional)
- `disabled`: When `true`, the link is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `activeClass`: Class to apply when the link is active (type `string`; optional)
- `exactActiveClass`: Class to apply when the link is exact active (type `string`; optional)
- `inactiveClass`: The class to apply to the link when it is inactive. (type `string`; optional)
- `prefetchedClass`: A class to apply to links that have been prefetched. (type `string`; optional)
- `ariaCurrentValue`: Value passed to the attribute `aria-current` when the link is exact active. (type `'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location'`; default ``'page'``; optional)
- `viewTransition`: Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported. (type `boolean`; optional)
- `rel`: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links. (type `(string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null`; default `'noopener noreferrer'`; optional)
- `noRel`: If set to true, no rel attribute will be added to the link (type `boolean`; optional)
- `prefetch`: When enabled will prefetch middleware, layouts and payloads of links in the viewport. (type `boolean`; optional)
- `prefetchOn`: Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility. (type `'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }>`; optional)
- `noPrefetch`: Escape hatch to disable `prefetch` attribute. (type `boolean`; optional)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href` for this specific link. Overrides the global `trailingSlash` option if provided. (type `'append' | 'remove'`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the link into a headless layer (route detection, disabled handling, `RouterLink` integration) and a styled layer (`linkVariants` styling). This differs from single-package solutions like Nuxt Link, React Router Link, and Next.js Link.

| Aspect          | SoybeanUI                                                           | Nuxt Link / React Router Link / Next.js Link |
| :-------------- | :------------------------------------------------------------------ | :------------------------------------------- |
| Architecture    | headless + styled split                                             | single package                               |
| Route detection | auto-detect `http` prefix, `external` prop, RouterLink availability | explicit `<NuxtLink>` / `<Link>`             |
| External links  | auto `target="_blank"` + `rel="noopener noreferrer"`                | manual setup required                        |
| Disabled state  | `aria-disabled` + `tabindex="-1"` + `preventDefault`                | manual handling required                     |
| Polymorphism    | `as`/`asChild` via `Primitive`                                      | `as` / `passHref`                            |
| Styling         | UnoCSS utility classes + `linkVariants`                             | CSS Modules / styled / none                  |

### FAQ

**When to use `to` vs `href`?**
Use `to` for internal route navigation (requires `RouterLink`) and `href` for external links. When `to` is a string starting with `http`, the component automatically treats it as an external link and renders an `<a>` tag.

**Can I use it without vue-router installed?**
Yes. The component uses `resolveComponent('RouterLink')` to check if RouterLink is available. When unavailable, it automatically falls back to rendering an `<a>` tag.

**Can I plug in a framework-specific link component (Nuxt `NuxtLink`, a locale-prefixing `Link`)?**
Yes. Set `linkComponent` on `SConfigProvider` (same injection mechanism as `iconRender`); `Link` then renders internal links with that component instead of the global `RouterLink`. Framework-specific props that `LinkProps` does not declare (e.g. `locale`) fall through as attrs to the injected component, and you can type them via module augmentation of `LinkProps`. External links still render a native `<a>`.

**How do I disable a link?**
Set `disabled: true`. The component sets `aria-disabled="true"`, `tabindex="-1"`, `role="link"`, and calls `preventDefault()` to block click navigation. The `data-disabled` attribute is added to trigger `cursor-not-allowed` and `opacity-50` visually.

**What's the difference between `as` and `asChild`?**
`as` specifies the root element tag (e.g., `as="button"` renders a `<button>`). `asChild` makes the component not render its own root element, instead forwarding attributes and events to its child (similar to Radix UI's `asChild` pattern).

**What are the default values for `target` and `rel`?**
External links default to `target="_blank"`, `rel="noopener noreferrer"`; internal routes default to `target="_self"`. Both can be overridden via props.

## List

- Page URL: /components/list
- Markdown URL: /components/list.md
- Description: A semantic container for displaying a vertical list of items. SList and SListItem are UI-only components: they render the <ul>/<li> and item/content/title/description anatomy themselves, styled by the listVariants style recipe (5 slots: root/item/content/title/description; 6 sizes).

# List

## Overview

A semantic container for displaying a vertical list of items. `SList` and `SListItem` are **UI-only**: they render the `<ul>`/`<li>` and the item/content/title/description anatomy themselves and share the `listVariants` style recipe (5 slots: root/item/content/title/description; 6 sizes) over a small UI-level context.

Use it for user lists, settings/menu groups, notification feeds, or any simple vertical collection. Prefer `table` for tabular data with columns and sorting, `tree` for hierarchical data, and `select`/`combobox` for selectable option lists.

There is no headless `list` family: a plain `ul`/`li` carries no keyboard, focus or ARIA-widget logic of its own, so it has no place in the headless layer. Interactive lists are served by the admitted `listbox` / `tree` families instead.

## Usage

Usage examples for list are rendered on the site.

## Features

- 🧩 UI-only anatomy shell — `SList`/`SListItem` own the markup and share `listVariants` classes through a UI-level `provideListUi` context; no headless `list` family exists
- 📋 Semantic markup — renders a real `<ul>`/`<li>` with `data-soybean-list-*` hooks
- 🏷️ Item composition — `SListItem` renders an optional `title` + `description` block via `title`/`description` props or slots
- ↔️ Leading / trailing — `leading`/`trailing` slots on `SListItem` for icons, badges, avatars or actions
- 🎨 6 sizes — xs–2xl `size` matching `ThemeSize`
- 🎛️ Per-slot control — `contentProps`/`titleProps`/`descriptionProps` forwarded to each item part
- ♿ Accessible by default — semantic list semantics and zero `axe-core` violations

## Component family

- `SList` — the list container; renders the `<ul>` with the `root` slot and provides `listVariants` to its items
- `SListItem` — the item row; renders the `<li>` plus the `item`/`content`/`title`/`description` nodes and exposes `leading`/`trailing`/`title`/`description`/default slots

## Demos

Interactive demos for list are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (6): List, ListContent, ListDescription, ListItem, ListRoot, ListTitle.

### List

#### Props
Properties for the List component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ListUi>`; optional)

### ListContent

- No documented props, emits, slots, or slot props were available.

### ListDescription

- No documented props, emits, slots, or slot props were available.

### ListItem

#### Props
Properties for the ListItem component.
- `class`: Additional class names applied to the item element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `contentProps`: Properties forwarded to the content element. (type `ListContentProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `ListTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `ListDescriptionProps`; optional)
#### Slots
Slots for the ListItem component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `title`: Custom content for the title slot. (type `(() => any) | undefined`)
- `description`: Custom content for the description slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)

### ListRoot

- No documented props, emits, slots, or slot props were available.

### ListTitle

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`SList`/`SListItem` are UI-only: a plain `ul`/`li` anatomy shell failed the headless deletion test, so the family was removed from the headless layer and the markup now lives in the UI layer, with all styling in `listVariants` and the slot classes passed down through `provideListUi`. This mirrors shadcn/ui's composition-first approach, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a config-driven list (`dataSource`/`renderItem`). SoybeanUI deliberately keeps `SList` a presentational container — data iteration stays with the consumer — so very large data is handled by the standalone `virtualizer` component rather than a built-in virtual scroll. Interactive lists use `listbox` / `tree` instead of `SList`.

| Capability                | SoybeanUI | shadcn/ui | Ant Design List | Element Plus | Mantine List | Naive UI |
| :------------------------ | :-------: | :-------: | :-------------: | :----------: | :----------: | :------: |
| Headless/styled split     |    ✅     |    ✅     |        —        |      —       |      —       |    —     |
| Semantic `ul`/`li` markup |    ✅     |    ✅     |       ✅        |      ✅      |      ✅      |    ✅    |
| Title + description item  |    ✅     |     —     |       ✅        |      ✅      |      ✅      |    ✅    |
| Leading / trailing slots  |    ✅     |     —     |       ✅        |      ✅      |      ✅      |    ✅    |
| Size variants (6)         |    ✅     |     —     |       ✅        |      ✅      |      ✅      |    ✅    |
| Built-in virtual scroll   |    ➕     |     —     |       ✅        |      —       |      ✅      |    ✅    |

`—` = unsupported or a different interaction model; `➕` = valuable enhancement (delegated to `virtualizer`).

### Cautions

- `SList` is a presentational container: it does not own data iteration or virtual scrolling. For 1k+ items render the items directly or compose them with the standalone `virtualizer` component.
- Items render as `<li>` inside a `<ul>`. Keep the direct children list items and avoid nesting full interactive blocks that break list semantics.
- Use `SListItem` for a title + description row; for a plain list you can also drop raw `<li>` elements into `SList`.
- The item `title` renders as an `<h3>` and the `description` as a `<p>`; if the list is part of a document outline, pick `size`/`class` or your own markup so the heading level still fits.

### Roadmap

A built-in virtualized list or a `dataSource`/`renderItem` config mode is evaluated as an enhancement, delegated to the standalone `virtualizer` today (see `docs/roadmap.md`).

## FAQ

### How do I build a list with title and description items?

Use `SListItem` with `title`/`description`:

```vue

  <SListItem title="Changelog" description="See what's new in v0.29" />
  <SListItem title="Guides" description="Step-by-step tutorials" />

```

### How do I add an icon or avatar to an item?

Use the `leading` slot (and `trailing` for actions):

```vue

  <template #leading><SAvatar src="/jenny.png" fallback-label="J" /></template>
  <template #trailing><SIcon icon="lucide:chevron-right" /></template>

```

### How do I change the list size?

Pass `size` (xs–2xl):

```vue

  <SListItem title="Large list" />

```

### How do I render a very large list efficiently?

`SList` is presentational — for 1k+ rows, render items directly or use the standalone `virtualizer` to keep only visible rows in the DOM.

### How do I make an item clickable?

Wrap the clickable surface yourself (a link or `SButton`), since a list item is not interactive by default:

```vue

  <SListItem title="Open profile">
    <template #trailing><a href="/profile" class="text-primary">View</a></template>
  </SListItem>

```

## Menu

- Page URL: /components/menu
- Markdown URL: /components/menu.md
- Description: The Menu component family lets you build complex nested menus, including dropdowns and context menus. It provides a data-driven approach using SMenuOptions, SMenuCheckboxOptions, and SMenuRadioOptions for easy configuration of groups, submenus, checkboxes, radio items, separators, shortcuts, and link items. The logic layer reuses @soybeanjs/headless/menu with full WAI-ARIA menu semantics and roving-focus keyboard navigation.

# Menu

## Overview

The Menu component family lets you build complex nested menus, including dropdowns and context menus. It provides a data-driven approach using `SMenuOptions`, `SMenuCheckboxOptions`, and `SMenuRadioOptions` for easy configuration of groups, submenus, checkboxes, radio items, separators, shortcuts, and link items. The logic layer reuses `@soybeanjs/headless/menu` with full WAI-ARIA menu semantics and roving-focus keyboard navigation.

## Features

- **Data-driven compact composition** — `SMenuOptions` / `SMenuCheckboxOptions` / `SMenuRadioOptions` recursively render items from an `items` array; the headless `MenuOptionsCompact` owns iteration, default assembly, and submenu recursion.
- **Full WAI-ARIA menu semantics** — `role="menu"` / `menuitem` / `menuitemcheckbox` / `menuitemradio`, `aria-checked` (including `'mixed'`), `aria-haspopup`, `aria-expanded`, `aria-controls`, `aria-disabled`.
- **Full keyboard navigation** — roving-focus arrow movement (dir-aware), typeahead character search (skips disabled), Home/End/PageUp/PageDown jumps, Enter/Space selection, Esc close + focus return, Tab loop inside the menu, and submenu open/close arrow keys.
- **Floating positioning** — built on `@floating-ui/dom` (`autoUpdate` + `arrow`/`flip`/`hide`/`limitShift`/`offset`/`shift`/`size` middleware) with arrow, placement, sideOffset, and CSS variable forwarding.
- **Three data shapes** — plain `MenuOptionData` (icon/shortcut/separator/link/submenu), checkbox `MenuCheckboxOptionData` (`CheckedState` including `'mixed'`), and radio `MenuRadioOptionData` (`AcceptableBooleanValue`), each with its own group.
- **Grouping & separators** — `isGroupLabel` renders a `MenuGroupLabel` heading, `separator` renders a divider, and `shortcut` renders a keyboard hint.
- **Floating lifecycle** — dismissable layer (outside pointer / Esc close), Presence (exit animation + `forceMount`), body scroll lock, focus scope/trap, and modal mode.
- **Disabled items** — per-item `disabled` with `itemProps.disabled` fallback (explicit value wins), `aria-disabled` + `tabindex="-1"`.
- **Hidden items** — per-item `hidden` drops the option (and its whole subtree) from rendering, the active-path search and keyboard navigation; an item whose children are all hidden renders as a leaf.
- **Headless composition** — `MenuRoot` / `MenuContent` / `MenuItem` / `MenuCheckboxItem` / `MenuRadioItem` / `MenuSub` / `MenuGroup` exported from `@soybeanjs/headless/menu`, reused by dropdown-menu, context-menu, and menubar.

## Component family

- **`SMenuOptions`** — data-driven list of plain menu items (with submenus/links/separators/shortcuts).
- **`SMenuOption`** — the recursive item component used internally by `SMenuOptions` (can be used standalone).
- **`SMenuCheckboxOptions`** — a group of checkbox items (`v-model` array / `CheckedState`).
- **`SMenuRadioOptions`** — a group of radio items (`v-model` bound to `AcceptableBooleanValue`).

## Usage

Usage examples for menu are rendered on the site.

## Demos

Interactive demos for menu are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (27): ContextMenuPopup, MenuAnchor, MenuArrow, MenuCheckboxGroup, MenuCheckboxItem, MenuCheckboxOptionsCompact, MenuCheckboxOptionsCompactSelect, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuItemIndicator, MenuOptionCompact, MenuOptionCompactSelect, MenuOptionsCompact, MenuPortal, MenuRadioGroup, MenuRadioItem, MenuRadioOptionsCompact, MenuRadioOptionsCompactSelect, MenuRoot, MenuSeparator, MenuShortcut, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger.

### ContextMenuPopup

- No documented props, emits, slots, or slot props were available.

### MenuAnchor

- No documented props, emits, slots, or slot props were available.

### MenuArrow

- No documented props, emits, slots, or slot props were available.

### MenuCheckboxGroup

#### Props
Properties for the MenuCheckboxGroup component.
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuCheckboxGroup component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)

### MenuCheckboxItem

#### Props
Properties for the MenuCheckboxItem component.
- `modelValue`: The controlled checked state of the item. Can be used as `v-model`. (type `CheckedState`; optional)
- `value`: The value given as data when submitted with a `name`. (type `DefinedValue`; default `on`; optional)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `textValue`: Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. <br> Use this when the content is complex, or you have non-textual content inside. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuCheckboxItem component.
- `select`: Event handler called when the user selects an item (via mouse or keyboard). <br> Calling `event.preventDefault` in this handler will prevent the menu from closing when selecting that item. (type `[event: Event]`; parameters `event: Event`)
- `update:modelValue`: Event handler called when the checked state of the item changes. (type `[value: CheckedState]`; parameters `value: CheckedState`)

### MenuCheckboxOptionsCompact

#### Props
Properties for the MenuCheckboxOptionsCompact component.
- `items`: Items rendered by the component. (type `MenuCheckboxOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `MenuGroupLabelProps`; optional)
- `checkboxItemProps`: Properties forwarded to the checkbox item element. (type `MenuCheckboxItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `MenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `MenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the checkbox. Can be bound with v-model. (type `T[]`; optional)
- `defaultValue`: The value of the checkbox when it is initially rendered. Use when you do not need to control its value. (type `T[]`; optional)
- `disabled`: When `true`, prevents the user from interacting with the checkboxes (type `boolean`; default `false`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuCheckboxOptionsCompact component.
- `update:modelValue`: Event handler called when the value of the checkbox group changes. (type `[value: T[]]`; parameters `value: T[]`)
- `select`: Emitted when select occurs. (type `[item: MenuCheckboxOptionData<T>, event: Event]`; parameters `item: MenuCheckboxOptionData<T>, event: Event`)
#### Slots
Slots for the MenuCheckboxOptionsCompact component.
- `item`: Custom content for the item slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuCheckboxOptionData<T>) => any) | undefined`)

### MenuCheckboxOptionsCompactSelect

#### Emits
Events for the MenuCheckboxOptionsCompactSelect component.
- `select`: Emitted when select occurs. (type `[item: MenuCheckboxOptionData<T>, event: Event]`; parameters `item: MenuCheckboxOptionData<T>, event: Event`)

### MenuContent

#### Props
Properties for the MenuContent component.
- `popupProps`: Properties forwarded to the popup element. (type `MenuPopupProps`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
#### Emits
Events for the MenuContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### MenuGroup

#### Props
Properties for the MenuGroup component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### MenuGroupLabel

- No documented props, emits, slots, or slot props were available.

### MenuItem

#### Props
Properties for the MenuItem component.
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `textValue`: Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. <br> Use this when the content is complex, or you have non-textual content inside. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuItem component.
- `select`: Event handler called when the user selects an item (via mouse or keyboard). <br> Calling `event.preventDefault` in this handler will prevent the menu from closing when selecting that item. (type `[event: Event]`; parameters `event: Event`)

### MenuItemIndicator

#### Props
Properties for the MenuItemIndicator component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### MenuOptionCompact

#### Props
Properties for the MenuOptionCompact component.
- `item`: Current item data. (type `MenuOptionData<T>`; required)
- `itemProps`: Properties forwarded to the item element. (type `MenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `MenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `MenuGroupLabelProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `MenuSubProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `MenuSubTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `MenuPortalProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `MenuSubContentProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `MenuSeparatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
#### Emits
Events for the MenuOptionCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the MenuOptionCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)

### MenuOptionCompactSelect

#### Emits
Events for the MenuOptionCompactSelect component.
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)

### MenuOptionsCompact

#### Props
Properties for the MenuOptionsCompact component.
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `MenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `MenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `MenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `MenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `MenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `MenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `MenuSubContentProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `MenuPortalProps`; optional)
#### Emits
Events for the MenuOptionsCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the MenuOptionsCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)

### MenuPortal

- No documented props, emits, slots, or slot props were available.

### MenuRadioGroup

#### Props
Properties for the MenuRadioGroup component.
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuRadioGroup component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: Exclude<T, undefined> | null]`; parameters `payload: Exclude<T, undefined> | null`)

### MenuRadioItem

#### Props
Properties for the MenuRadioItem component.
- `value`: The value given as data when submitted with a `name`. (type `string | number | boolean`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `textValue`: Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. <br> Use this when the content is complex, or you have non-textual content inside. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuRadioItem component.
- `select`: Event handler called when the user selects an item (via mouse or keyboard). <br> Calling `event.preventDefault` in this handler will prevent the menu from closing when selecting that item. (type `[event: Event]`; parameters `event: Event`)

### MenuRadioOptionsCompact

#### Props
Properties for the MenuRadioOptionsCompact component.
- `items`: Items rendered by the component. (type `MenuRadioOptionData<T>[]`; required)
- `groupLabelProps`: Properties forwarded to the group label element. (type `MenuGroupLabelProps`; optional)
- `radioItemProps`: Properties forwarded to the radio item element. (type `MenuRadioItemProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `MenuItemIndicatorProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `MenuSeparatorProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenuRadioOptionsCompact component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: Exclude<T, undefined> | null]`; parameters `payload: Exclude<T, undefined> | null`)
- `select`: Emitted when select occurs. (type `[item: MenuRadioOptionData<T>, event: Event]`; parameters `item: MenuRadioOptionData<T>, event: Event`)
#### Slots
Slots for the MenuRadioOptionsCompact component.
- `item`: Custom content for the item slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)
- `item-indicator-icon`: Custom content for the item indicator icon slot. (type `((props: MenuRadioOptionData<T>) => any) | undefined`)

### MenuRadioOptionsCompactSelect

#### Emits
Events for the MenuRadioOptionsCompactSelect component.
- `select`: Emitted when select occurs. (type `[item: MenuRadioOptionData<T>, event: Event]`; parameters `item: MenuRadioOptionData<T>, event: Event`)

### MenuRoot

#### Props
Properties for the MenuRoot component.
- `dir`: The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. (type `boolean`; default `true`; optional)
#### Emits
Events for the MenuRoot component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### MenuSeparator

- No documented props, emits, slots, or slot props were available.

### MenuShortcut

#### Props
Properties for the MenuShortcut component.
- `symbolize`: Whether to convert the command value to symbol representation. (type `boolean`; default `true`; optional)

### MenuSub

#### Props
Properties for the MenuSub component.
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
#### Emits
Events for the MenuSub component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### MenuSubContent

#### Props
Properties for the MenuSubContent component.
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `MenuPopupProps`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the MenuSubContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### MenuSubTrigger

#### Props
Properties for the MenuSubTrigger component.
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `textValue`: Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. <br> Use this when the content is complex, or you have non-textual content inside. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### MenuTrigger

#### Props
Properties for the MenuTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark comparison

| Concern                  | SoybeanUI                                | Radix UI Menu   | Ant Design Menu / Dropdown | Element Plus Dropdown |
| :----------------------- | :--------------------------------------- | :-------------- | :------------------------- | :-------------------- |
| Headless / styled split  | ✅ `@soybeanjs/headless/menu` + `scv()`  | ✅ headless     | ❌ single package          | ❌ single package     |
| Data-driven compact API  | ✅ plain/checkbox/radio                  | ❌ composition  | ✅ config-driven (items)   | ✅ config-driven      |
| roving focus + typeahead | ✅ full model (Home/End/PageUp/PageDown) | ✅              | partial                    | partial               |
| Submenu arrow keys       | ✅ ArrowRight/Left (dir-aware)           | ✅              | partial                    | partial               |
| Checkbox / radio items   | ✅ `menuitemcheckbox` / `menuitemradio`  | ✅              | ✅                         | partial               |
| `'mixed'` indeterminate  | ✅ `CheckedState`                        | ✅              | ✅                         | —                     |
| Floating positioning     | ✅ floating-ui (arrow/size/flip/…)       | ✅              | ✅                         | ✅                    |
| Separator / shortcut     | ✅ `separator` / `shortcut`              | component combo | ✅ (divider / command)     | partial               |
| Grouping                 | ✅ `isGroupLabel` + `MenuGroupLabel`     | ✅ `MenuGroup`  | ✅ (type:'group')          | partial               |

`—` = not supported or uses a different interaction model.

### Runtime considerations

1. **`items` data shape** — `MenuOptionData` includes `label`/`value`/`icon`/`shortcut`/`separator`/`isGroupLabel`/`children`; `children` recursively renders submenus. Checkbox/radio shapes each have their own type.
2. **Controlled / uncontrolled** — checkbox and radio groups support `modelValue` / `defaultValue` (`useControllableState`); a radio group's `modelValue` can be `null` (no selection).
3. **Keyboard activation** — roving focus is maintained by `useRovingFocusGroup`; typeahead jumps by character (skipping disabled); `Esc` closes via `useDismissableLayer` and returns focus to the trigger.
4. **Disabled fallback** — per-item `disabled` wins over `itemProps.disabled`; disabled items are `aria-disabled` + `tabindex="-1"` but stay registered so typeahead can skip them.
5. **Floating lifecycle** — dismissable layer + Presence (`forceMount`); body scroll lock and focus scope are enabled when Root's modal mode is on.
6. **Link items** — items with `href`/`to` render as links (reusing the Link primitive); `itemProps` / `linkProps` forward attributes.
7. **`select` event payload** — `select(item, event)` carries the selected item and the native event; the menu close can be controlled via `event.defaultPrevented`.

## FAQ

### How do I create an item with a submenu?

Provide a `children` array on the `MenuOptionData` to render a submenu recursively; submenus support further nesting.

### How do checkbox and radio items bind values?

Checkbox uses `v-model` bound to an array (`CheckedState[]`, supports `'mixed'`); radio uses `v-model` bound to an `AcceptableBooleanValue` (can be `null` for no selection).

### How do I add separators and shortcuts?

Set `separator: true` on an item to render a divider after it; set `shortcut` (`KbdValue` or array) to render a keyboard hint at the item's end.

### How does keyboard navigation work?

Arrow keys move focus (dir-aware); typing letters triggers typeahead; `Home`/`End` jump to first/last; `Enter`/`Space` select; `Esc` closes and returns focus; `Tab` loops inside the menu; submenus open/close via `ArrowRight`/`ArrowLeft`.

### Can I build a fully custom menu?

Yes — compose `MenuRoot` / `MenuContent` / `MenuItem` / `MenuCheckboxItem` / `MenuRadioItem` / `MenuSub` / `MenuGroup` primitives from `@soybeanjs/headless/menu` and inject styles via `provideMenuUi` (or `SMenuOptions`'s `ui` prop).

## Menubar

- Page URL: /components/menubar
- Markdown URL: /components/menubar.md
- Description: Menubar builds a persistent horizontal menu bar for application chrome: a row of triggers with roving focus that open dropdown menus on click or hover, with arbitrarily nested submenus and full keyboard navigation.

# Menubar

## Overview

Menubar builds a persistent horizontal menu bar for application chrome: a row of triggers with roving focus that open dropdown menus on click or hover, with arbitrarily nested submenus and full keyboard navigation.

`SMenubar` is a data-driven aggregation component: pass an `items` array and it renders the full `role="menubar"` structure, triggers, dropdown content, and nested submenus. A top-level item can be either a trigger that opens a dropdown or a link that navigates (set `href` / `to`). Logic and accessibility semantics live in the headless `MenubarCompact`; styles are injected through a `scv()` recipe.

> `SMenubar` delegates all structural composition to the headless `MenubarCompact`. For unstyled data-driven usage, import from `@soybeanjs/headless/menubar`; the dropdown layer reuses `MenuOptionsCompact` from `@soybeanjs/headless/menu`.

## Features

- **Data-driven composition** — pass `items` (`MenuOptionData`) to render the menubar; top-level items declare dropdowns via `children`, and child items support `label` / `icon` / `shortcut` / `disabled` / `separator` / `href` / `to` with unlimited nesting.
- **Horizontal roving focus** — the root keeps a single tab stop; `ArrowLeft` / `ArrowRight` move focus between triggers and `loop` wraps around at the ends; disabled triggers drop out of the focus order.
- **Full keyboard navigation** — `Enter` / `Space` toggle the menu and `ArrowDown` opens it; arrow keys roam menu items, `ArrowRight` / `ArrowLeft` switch between neighboring top-level menus; `Escape` closes and restores focus.
- **Hover / pointer switching** — with a menu open, hovering another trigger switches the open menu; hovering a link trigger dismisses the menu and focuses the link.
- **Click / hover trigger modes** — `trigger` supports `click` (default) and `hover`: `click` opens on click while hovering an open menubar still switches menus; `hover` opens on hover (tune with `delayDuration` / `skipDelayDuration`) and includes a pointer grace area so the pointer can move between the menubar and the content without accidental closes.
- **Overflow collapsing** — with `collapsible`, when the menubar content is wider than its container, trailing top-level items merge into a trailing "more" menu so the content always fits; customize via `moreLabel` / `moreIcon` / `moreProps` / the `more-trigger` slot.
- **Link top-level items** — items with `href` / `to` render as links (no dropdown), matching the `nav-menu` pattern; link semantics for `target` / `external` / `disabled` are preserved.
- **Nested submenus** — child items render arbitrarily deep submenus via `MenuSub`, with arrow-key entry/exit and a pointer-grace debounce (100ms open delay).
- **Controlled / uncontrolled** — with `modelValue`, the open menu follows the prop and emits `update:modelValue`; otherwise `defaultValue` seeds the initial state.
- **Per-item and whole-bar disabling** — `item.disabled` makes a single top-level trigger fully inert (`aria-disabled` + out of tab order + blocked interaction); the compact-level `disabled` prop disables every trigger at once, including link triggers.
- **Hidden items** — `item.hidden` drops a top-level trigger and its dropdown; hidden items are filtered before the overflow math, so `collapsible` only counts visible triggers. Hidden child items are dropped from their dropdown.
- **Bidirectional direction** — `dir` supports LTR / RTL; arrow keys and submenu slide direction follow logical direction; `portalProps` controls whether content teleports to `body`.
- **Six sizes** — `size` (xs…2xl) variants cover root and trigger spacing, padding, and font size.
- **Menu slot passthrough** — `item-leading` / `item-trailing` / `trigger` / `item-link-icon` slots forward to the menu layer for per-item customization; the `ui` prop overrides root and trigger slots.
- **Headless composition** — `MenubarRoot` / `MenubarMenu` / `MenubarTrigger` / `MenubarContent` / `MenubarSubTrigger` / `MenubarSubContent` and `Compact` are all exported from `@soybeanjs/headless/menubar`; menu primitives are reused from `@soybeanjs/headless/menu`.

## Usage

Usage examples for menubar are rendered on the site.

## Demos

Interactive demos for menubar are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (21): Menubar, MenubarArrow, MenubarCheckboxGroup, MenubarCheckboxItem, MenubarCompact, MenubarContent, MenubarGroup, MenubarGroupLabel, MenubarItem, MenubarItemIndicator, MenubarMenu, MenubarMenus, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarRoot, MenubarSeparator, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger.

### Menubar

#### Props
Properties for the Menubar component.
- `class`: class of menubar root (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<MenubarUi>`; optional)
- `indicatorPosition`: Indicator position. (type `AlignSide`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `MenubarTriggerProps`; optional)
- `collapsible`: When `true`, if the menubar content is wider than its container, the trailing items collapse into a trailing "more" menu so the content always fits inside the container. (type `boolean`; optional)
- `moreLabel`: Label of the trailing "more" trigger when `collapsible`. (type `string`; default `undefined`; optional)
- `moreIcon`: Icon of the trailing "more" trigger when `collapsible`. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)
- `moreProps`: Properties forwarded to the trailing "more" trigger. (type `MenubarTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `MenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `MenubarContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `MenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `MenuArrowProps`; optional)
- `modelValue`: The controlled value of the menu to open. Can be used as `v-model`. (type `T`; optional)
- `defaultValue`: The value of the menu that should be open when initially rendered. (type `T`; optional)
- `dir`: The reading direction of the menubar when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation loops from last trigger to first and vice versa. (type `boolean`; optional)
- `trigger`: The trigger type of the menubar. - `click`: The menu will be opened when the trigger is clicked (hovering an open menubar still switches between menus). - `hover`: The menu will be opened when the trigger is hovered. (type `MenubarTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the menu gets opened in hover mode. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `MenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `MenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `MenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `MenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `MenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `MenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `MenuSubContentProps`; optional)
#### Emits
Events for the Menubar component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: T]`; parameters `value: T`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the Menubar component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. Optional: `MenubarCompact` renders full default trigger content (icon, label, link icon, trailing slot) when the consumer does not provide it. (type `((data: { item: MenuOptionData<T>; }) => any) | undefined`)
- `more-trigger`: Custom content for the trailing "more" trigger when `collapsible`. (type `(() => any) | undefined`)

### MenubarArrow

- No documented props, emits, slots, or slot props were available.

### MenubarCheckboxGroup

- No documented props, emits, slots, or slot props were available.

### MenubarCheckboxItem

- No documented props, emits, slots, or slot props were available.

### MenubarCompact

#### Props
Properties for the MenubarCompact component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `MenubarTriggerProps`; optional)
- `collapsible`: When `true`, if the menubar content is wider than its container, the trailing items collapse into a trailing "more" menu so the content always fits inside the container. (type `boolean`; optional)
- `moreLabel`: Label of the trailing "more" trigger when `collapsible`. (type `string`; default `undefined`; optional)
- `moreIcon`: Icon of the trailing "more" trigger when `collapsible`. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)
- `moreProps`: Properties forwarded to the trailing "more" trigger. (type `MenubarTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `MenuPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `MenubarContentProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `MenuPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `MenuArrowProps`; optional)
- `modelValue`: The controlled value of the menu to open. Can be used as `v-model`. (type `T`; optional)
- `defaultValue`: The value of the menu that should be open when initially rendered. (type `T`; optional)
- `dir`: The reading direction of the menubar when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation loops from last trigger to first and vice versa. (type `boolean`; optional)
- `trigger`: The trigger type of the menubar. - `click`: The menu will be opened when the trigger is clicked (hovering an open menubar still switches between menus). - `hover`: The menu will be opened when the trigger is hovered. (type `MenubarTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the menu gets opened in hover mode. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `items`: Items rendered by the component. (type `MenuOptionData<T>[]`; required)
- `selectedValue`: The selected value of the menu. (type `T`; optional)
- `itemProps`: Properties forwarded to the item element. (type `MenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `MenuSubProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `MenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `MenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `MenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element. (type `MenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element. (type `MenuSubContentProps`; optional)
#### Emits
Events for the MenubarCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: T]`; parameters `value: T`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `select`: Emitted when select occurs. (type `[item: MenuOptionData<T>, event: Event]`; parameters `item: MenuOptionData<T>, event: Event`)
#### Slots
Slots for the MenubarCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<T>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<T>; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. Optional: `MenubarCompact` renders full default trigger content (icon, label, link icon, trailing slot) when the consumer does not provide it. (type `((data: { item: MenuOptionData<T>; }) => any) | undefined`)
- `more-trigger`: Custom content for the trailing "more" trigger when `collapsible`. (type `(() => any) | undefined`)

### MenubarContent

#### Props
Properties for the MenubarContent component.
- `popupProps`: Properties forwarded to the popup element. (type `MenuPopupProps`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
#### Emits
Events for the MenubarContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### MenubarGroup

- No documented props, emits, slots, or slot props were available.

### MenubarGroupLabel

- No documented props, emits, slots, or slot props were available.

### MenubarItem

- No documented props, emits, slots, or slot props were available.

### MenubarItemIndicator

- No documented props, emits, slots, or slot props were available.

### MenubarMenu

#### Props
Properties for the MenubarMenu component.
- `value`: A unique value that associates the trigger with the active root value when controlled. (type `DefinedValue`; optional)

### MenubarMenus

#### Props
Properties for the MenubarMenus component (the internal list renderer used
by `MenubarCompact`).
- `items`: Top-level items rendered as visible triggers. (type `MenuOptionData<T>[]`; required)
- `moreItems`: Items collapsed into the trailing "more" menu. (type `MenuOptionData<T>[]`; required)
- `rootProps`: Props forwarded to the menubar root. (type `{ [x: string]: unknown; }`; required)
- `listeners`: Listeners forwarded to the menubar root. (type `{ [x: string]: unknown; }`; required)
- `optionsProps`: Props forwarded to the menu options of each open menu. (type `{ [x: string]: unknown; }`; required)
- `linkProps`: Props forwarded to link triggers. (type `LinkExtraProps`; optional)
- `contentProps`: Props forwarded to the content of each menu. (type `MenubarContentProps`; required)
- `portalProps`: Props forwarded to the portal of each menu. (type `MenuPortalProps`; optional)
- `getTriggerProps`: Resolve the effective props of a top-level trigger item. (type `(item: MenuOptionData<T>) => MenubarTriggerProps`; required)
- `moreTriggerProps`: Props forwarded to the trailing "more" trigger. (type `{ [x: string]: unknown; }`; required)
- `moreLabel`: Label of the trailing "more" trigger. (type `string`; optional)
- `moreIcon`: Icon of the trailing "more" trigger. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; optional)

### MenubarPortal

- No documented props, emits, slots, or slot props were available.

### MenubarRadioGroup

- No documented props, emits, slots, or slot props were available.

### MenubarRadioItem

- No documented props, emits, slots, or slot props were available.

### MenubarRoot

#### Props
Properties for the MenubarRoot component.
- `modelValue`: The controlled value of the menu to open. Can be used as `v-model`. (type `T`; optional)
- `defaultValue`: The value of the menu that should be open when initially rendered. (type `T`; optional)
- `dir`: The reading direction of the menubar when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation loops from last trigger to first and vice versa. (type `boolean`; optional)
- `trigger`: The trigger type of the menubar. - `click`: The menu will be opened when the trigger is clicked (hovering an open menubar still switches between menus). - `hover`: The menu will be opened when the trigger is hovered. (type `MenubarTriggerType`; default `'click'`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the menu gets opened in hover mode. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the MenubarRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: T]`; parameters `value: T`)

### MenubarSeparator

- No documented props, emits, slots, or slot props were available.

### MenubarSub

- No documented props, emits, slots, or slot props were available.

### MenubarSubContent

#### Props
Properties for the MenubarSubContent component.
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `MenuPopupProps`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the MenubarSubContent component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `entryFocus`: Emitted when entry focus occurs. (type `[event: Event]`; parameters `event: Event`)

### MenubarSubTrigger

#### Props
Properties for the MenubarSubTrigger component.
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `textValue`: Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. <br> Use this when the content is complex, or you have non-textual content inside. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### MenubarTrigger

#### Props
Properties for the MenubarTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture & benchmark comparison

| Capability              | SoybeanUI                                               | Ant Design `Menu`              | Element Plus `Menu` | Radix `Menubar`              |
| :---------------------- | :------------------------------------------------------ | :----------------------------- | :------------------ | :--------------------------- |
| headless/styled split   | ✅ `@soybeanjs/headless/menubar` + `scv()`              | ❌ single package              | ❌ single package   | ✅ `@radix-ui/react-menubar` |
| Data-driven compact API | ✅ `MenubarCompact` + nested `items`                    | ✅ `items`                     | ✅ `items`          | ❌ JSX composition           |
| Top-level triggers      | ✅ click / hover switch + arrows                        | ✅ click / hover               | ✅ click / hover    | ✅ click / hover + arrows    |
| Horizontal roving       | ✅ Roving Focus + `loop`                                | ✅                             | ✅                  | ✅                           |
| Cross-menu switching    | ✅ `ArrowRight` / `ArrowLeft`                           | ✅                             | ✅                  | ✅                           |
| Nested submenus         | ✅ any depth (reuses menu layer)                        | ✅ `SubMenu`                   | ✅ `el-sub-menu`    | ✅                           |
| Link top-level items    | ✅ `href` / `to` + `target` / `external` / `disabled`   | ✅ `danger` etc.               | —                   | ✅ `LinkItem`                |
| Disabled                | ✅ per-item + compact-wide                              | ✅ `disabled`                  | ✅ `disabled`       | ✅ `disabled`                |
| Controlled mode         | ✅ `modelValue` / `defaultValue`                        | ✅ `openKeys` / `selectedKeys` | ✅ `default-active` | ✅ `value` / `onValueChange` |
| Direction               | ✅ LTR / RTL + logical arrow keys                       | ✅ RTL                         | ✅ RTL              | ✅ RTL                       |
| Size variants           | ✅ `size` xs…2xl                                        | ✅ `size`                      | ✅ `size`           | —                            |
| Menu item types         | ✅ checkbox / radio / separator / shortcut (menu layer) | ✅ full                        | ✅ full             | ✅ full                      |

### Runtime considerations

1. **Open state and pointer** — in the default mode (`trigger="click"`), top-level triggers open their menu on `pointerdown`; clicking the same trigger again while open closes it via the dismissable layer ("click again to collapse"). Hovering another trigger switches the open menu. With `trigger="hover"` the menu opens on hover; `delayDuration` (default 150ms) controls the open delay and `skipDelayDuration` (default 300ms) the no-delay re-open window.
2. **Link top-level items** — items with `href` / `to` render no dropdown; clicking or keyboard activation navigates directly. Hovering a link item while a menu is open collapses the menu and moves focus to the link.
3. **Disabled semantics** — `item.disabled` targets a single top-level item: `aria-disabled`, `tabindex="-1"`, and blocked click/keyboard activation. The compact-level `disabled` disables every trigger (including link triggers). Disabled child items follow menu-layer semantics.
4. **Portal and positioning** — dropdown content teleports to `body` by default (disable via `portalProps.disabled`). If content appears in the wrong place, check for `transform` / animation-container ancestors; positioning relies on `getBoundingClientRect` measurements.
5. **Controlled / uncontrolled** — with `modelValue`, internal writes only emit `update:modelValue` and the open menu fully follows the prop; uncontrolled usage seeds the initial state with `defaultValue`.
6. **Focus restoration** — keyboard paths (`Escape` / arrow switching) restore focus to the trigger precisely; pointer paths (click outside to close) do not move focus, matching the "pointer interaction does not hijack focus" convention.
7. **RTL** — with `dir="rtl"`, arrow-key semantics mirror (`ArrowLeft` becomes "next") and menu layout flips via logical properties.
8. **Overflow collapsing** — with `collapsible`, trailing items merge into the "more" menu when the content overflows its container; measurement runs against the real rendered layout, so the container's parent must provide a fixed/constrained width (e.g. `max-w-*`). If the menubar sits in a flex container that does not shrink, set `min-w-0` or a width constraint on the parent.

## FAQ

### How do I make a top-level item navigate instead of opening a dropdown?

Set `href` or `to` on the item — link top-level items render as an `<a>` with no dropdown; use `target` / `external` to control how the link opens.

### How do I precisely control which menu is open?

Bind `modelValue` with `v-model`. The top-level item `value` becomes the controlled value; activation emits `update:modelValue`, and external changes sync the open menu. Uncontrolled usage seeds the initial state with `defaultValue`.

### How do I disable the whole menubar or single items?

Pass `disabled` to `SMenubar` to disable everything, or set `disabled: true` on a single top-level item. Disabled items render `aria-disabled`, drop out of tab order, and block click and keyboard activation.

### What is the keyboard flow?

`Tab` enters the menubar; `ArrowLeft` / `ArrowRight` move between triggers; `Enter` / `Space` toggle a menu and `ArrowDown` opens it; inside a menu, arrow keys roam items, `ArrowRight` / `ArrowLeft` switch to neighboring top-level menus, and `Escape` closes. Disabled items are excluded from tab order.

### Can I use checkboxes or radios inside submenus?

Yes — dropdown content reuses the menu layer: `item-checked` slots, `MenuCheckboxItem` / `MenuRadioItem`, plus `separator` / `shortcut` are all available; pass the matching fields on child items in compact usage.

### Why does the menu collapse when hovering a link item?

Link top-level items have no dropdown; on pointer enter the menubar collapses the currently open menu and moves focus to the link — matching Radix Menubar's link-item behavior and avoiding focus lingering on the trigger of a closed menu.

### How do I make the menu open on hover instead of on click?

Pass `trigger="hover"` to `SMenubar`. Hovering a trigger opens its menu (`delayDuration` controls the open delay, `skipDelayDuration` the re-open window); the pointer can move between the menubar and the menu content without accidental closes. Keyboard operation (arrows / Enter / Space / Escape) is identical in both modes.

### What if there are too many menu items to fit?

Pass `collapsible` to `SMenubar`. When the menubar content is wider than its container, trailing top-level items automatically merge into a trailing "more" menu (default label `More`, customizable via `moreLabel` / `moreIcon` / `moreProps`), so the content never exceeds the container width. The collapse state recomputes automatically when the container resizes.

## NavMenu

- Page URL: /components/nav-menu
- Markdown URL: /components/nav-menu.md
- Description: NavMenu builds site-level horizontal or vertical navigation with a single shared floating surface. It replaces the retired NavigationMenu family (see the NavMenu migration guide) and is modeled directly on the Popper primitives: the whole viewport is one PopperPositioner, its reference switches to the active trigger, and all hover timing runs on a single shared Popper hover machine with value routing through pendingValue.

# NavMenu

## Overview

NavMenu builds site-level horizontal or vertical navigation with a single shared floating surface. It replaces the retired `NavigationMenu` family (see the [NavMenu migration guide](/components/navigation-menu)) and is modeled directly on the Popper primitives: the whole viewport is one `PopperPositioner`, its reference switches to the active trigger, and all hover timing runs on a single shared Popper hover machine with value routing through `pendingValue`.

`SNavMenu` is a data-driven composite: pass an `items` array and it renders the `nav > ul > li` structure, trigger/content pairs, indicator, and the floating viewport. Styles are injected through an `scv()` recipe.

> For an unstyled, data-driven usage, import `@soybeanjs/headless/nav-menu`.

## Features

- **Single shared Popper model** — one `PopperRoot`, one `PopperPositioner` (the viewport), and a dynamic reference that switches to the active trigger. Positioning (Floating UI), the grace corridor and Escape/outside dismissal come from the positioner for free.
- **Value routing** — hover timing (open delay, skip-delay window) runs on the shared machine; the value of the most recently hovered trigger routes into `modelValue`, so switching between triggers is instant.
- **Hover / click triggers** — hover opens and click toggles by default; `disableClickTrigger` / `disableHoverTrigger` turn each trigger mode off independently.
- **Grace corridor** — moving between a trigger and the open viewport is protected by a real geometric corridor (no debounce), with `skipDelayDuration` and `disablePointerLeaveClose` tuning closing behavior.
- **Submenu surfaces** — items with `children` open a floating viewport anchored to their trigger, with an arrow indicator and `unmountOnHide` control.
- **Hidden items** — `hidden` drops an item and its whole subtree from the root list and from the nested flyouts; an item whose children are all hidden renders as a leaf link.
- **Keyboard navigation** — arrow keys move focus across items; `Enter` / `Space` activate a link or toggle a submenu; the entry arrow key moves focus into the content; `Escape` closes and restores focus to the trigger.
- **Popup arrow** — the viewport carries a `PopperArrow` that points at the active trigger; its placement and rotation come from Floating UI's `arrow` middleware, and it slides with the viewport on trigger switch.
- **Controlled / uncontrolled** — with `modelValue`, highlight follows the prop and `update:modelValue` fires; otherwise `defaultValue` seeds the initial open item.
- **Bidirectional** — `orientation` supports horizontal / vertical; `dir` supports LTR / RTL with logical placement.
- **Six sizes** — `size` (xs…2xl) variants cover spacing and type scale across the list, trigger, viewport, and links.
- **Headless composition** — `NavMenuRoot` / `List` / `Item` / `Trigger` / `Content` / `Link` / `Viewport` plus the `Compact` series are exported from `@soybeanjs/headless/nav-menu`.

## Usage

Usage examples for nav-menu are rendered on the site.

## Demos

Interactive demos for nav-menu are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (12): NavMenu, NavMenuCompact, NavMenuContent, NavMenuItem, NavMenuLink, NavMenuList, NavMenuOptionCompact, NavMenuRoot, NavMenuSubContent, NavMenuSubTrigger, NavMenuTrigger, NavMenuViewport.

### NavMenu

#### Props
Properties for the NavMenu component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<NavMenuUi>`; optional)
- `items`: The items to render in the navigation menu. (type `NavMenuOptionData[]`; required)
- `modelValue`: The controlled value of the active item. Can be used as `v-model`. (type `string`; optional)
- `defaultValue`: The value of the item that should be active when initially rendered. (type `string`; optional)
- `dir`: The reading direction of the menu. (type `Direction`; optional)
- `orientation`: The orientation of the menu. (type `DataOrientation`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the submenu opens. (type `number`; default `200`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableClickTrigger`: If `true`, the menu cannot be opened by clicking a trigger. (type `boolean`; default `false`; optional)
- `disableHoverTrigger`: If `true`, the menu cannot be opened by hovering a trigger. (type `boolean`; default `false`; optional)
- `disablePointerLeaveClose`: If `true`, the menu will not close when the pointer leaves the content. (type `boolean`; default `false`; optional)
- `itemProps`: Properties forwarded to the item element. (type `NavMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `Omit<NavMenuLinkProps, LinkBasePropsKey>`; optional)
- `subTriggerProps`: Properties forwarded to the nested flyout trigger element. (type `NavMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the nested flyout content element. (type `NavMenuSubContentProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `NavMenuTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `NavMenuContentProps`; optional)
- `listProps`: Properties forwarded to the list element. (type `NavMenuListProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `NavMenuViewportProps`; optional)
#### Emits
Events for the NavMenu component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when a link is selected. (type `[payload: CustomEvent<{ originalEvent: Event; }>]`; parameters `payload: CustomEvent<{ originalEvent: Event; }>`)
#### Slots
Slots for the NavMenu component.
- `item`: No description. (type `(props: { item: NavMenuOptionData; isTrigger?: boolean; }) => any`; parameters `props: { item: NavMenuOptionData; isTrigger?: boolean; }`)
- `item-leading`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-trailing`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-link-icon`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-trigger-icon`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-children`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)

### NavMenuCompact

#### Props
Properties for the NavMenuCompact component.
- `items`: The items to render in the navigation menu. (type `NavMenuOptionData[]`; required)
- `modelValue`: The controlled value of the active item. Can be used as `v-model`. (type `string`; optional)
- `defaultValue`: The value of the item that should be active when initially rendered. (type `string`; optional)
- `dir`: The reading direction of the menu. (type `Direction`; optional)
- `orientation`: The orientation of the menu. (type `DataOrientation`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the submenu opens. (type `number`; default `200`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableClickTrigger`: If `true`, the menu cannot be opened by clicking a trigger. (type `boolean`; default `false`; optional)
- `disableHoverTrigger`: If `true`, the menu cannot be opened by hovering a trigger. (type `boolean`; default `false`; optional)
- `disablePointerLeaveClose`: If `true`, the menu will not close when the pointer leaves the content. (type `boolean`; default `false`; optional)
- `itemProps`: Properties forwarded to the item element. (type `NavMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `Omit<NavMenuLinkProps, LinkBasePropsKey>`; optional)
- `subTriggerProps`: Properties forwarded to the nested flyout trigger element. (type `NavMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the nested flyout content element. (type `NavMenuSubContentProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `NavMenuTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `NavMenuContentProps`; optional)
- `listProps`: Properties forwarded to the list element. (type `NavMenuListProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `NavMenuViewportProps`; optional)
#### Emits
Events for the NavMenuCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when a link is selected. (type `[payload: CustomEvent<{ originalEvent: Event; }>]`; parameters `payload: CustomEvent<{ originalEvent: Event; }>`)
#### Slots
Slots for the NavMenuCompact component.
- `item`: No description. (type `(props: { item: NavMenuOptionData; isTrigger?: boolean; }) => any`; parameters `props: { item: NavMenuOptionData; isTrigger?: boolean; }`)
- `item-leading`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-trailing`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-link-icon`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-trigger-icon`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-children`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)

### NavMenuContent

#### Props
Properties for the NavMenuContent component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)

### NavMenuItem

#### Props
Properties for the NavMenuItem component.
- `value`: Value associated with the current item. (type `string`; optional)

### NavMenuLink

#### Props
Properties for the NavMenuLink component.
- `selected`: Marks the link as the currently selected page. (type `boolean`; optional)
- `sub`: Whether the link is rendered inside a submenu. When `true`, the `subLink` UI slot is used instead of `link` (mirroring the root/sub split of the list). (type `boolean`; optional)
- `replace`: Calls `router.replace` instead of `router.push`. (type `boolean`; optional)
- `disabled`: When `true`, the link is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `href`: The URL the link should navigate to when clicked on. (type `string`; optional)
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `activeClass`: Class to apply when the link is active (type `string`; optional)
- `exactActiveClass`: Class to apply when the link is exact active (type `string`; optional)
- `inactiveClass`: The class to apply to the link when it is inactive. (type `string`; optional)
- `prefetchedClass`: A class to apply to links that have been prefetched. (type `string`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `ariaCurrentValue`: Value passed to the attribute `aria-current` when the link is exact active. (type `'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location'`; default ``'page'``; optional)
- `viewTransition`: Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported. (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)
- `rel`: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links. (type `(string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null`; default `'noopener noreferrer'`; optional)
- `noRel`: If set to true, no rel attribute will be added to the link (type `boolean`; optional)
- `prefetch`: When enabled will prefetch middleware, layouts and payloads of links in the viewport. (type `boolean`; optional)
- `prefetchOn`: Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility. (type `'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }>`; optional)
- `noPrefetch`: Escape hatch to disable `prefetch` attribute. (type `boolean`; optional)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href` for this specific link. Overrides the global `trailingSlash` option if provided. (type `'append' | 'remove'`; optional)
#### Emits
Events for the NavMenuLink component.
- `select`: Emitted when a link is selected. (type `[payload: CustomEvent<{ originalEvent: Event; }>]`; parameters `payload: CustomEvent<{ originalEvent: Event; }>`)

### NavMenuList

- No documented props, emits, slots, or slot props were available.

### NavMenuOptionCompact

#### Props
Properties for the NavMenuOptionCompact component.
- `item`: Current item data. (type `NavMenuOptionData`; required)
- `itemProps`: Properties forwarded to the item element. (type `NavMenuItemProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `Omit<NavMenuLinkProps, LinkBasePropsKey>`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `NavMenuTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `NavMenuContentProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `NavMenuViewportProps`; optional)
- `listProps`: Properties forwarded to the list element. (type `NavMenuListProps`; optional)
- `subTriggerProps`: Properties forwarded to the nested flyout trigger element. (type `NavMenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the nested flyout content element. (type `NavMenuSubContentProps`; optional)
#### Emits
Events for the NavMenuOptionCompact component.
- `select`: Emitted when a link is selected. (type `[payload: CustomEvent<{ originalEvent: Event; }>]`; parameters `payload: CustomEvent<{ originalEvent: Event; }>`)
#### Slots
Slots for the NavMenuOptionCompact component.
- `item`: No description. (type `(props: { item: NavMenuOptionData; isTrigger?: boolean; }) => any`; parameters `props: { item: NavMenuOptionData; isTrigger?: boolean; }`)
- `item-leading`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-trailing`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-link-icon`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-trigger-icon`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)
- `item-children`: No description. (type `(props: { item: NavMenuOptionData; }) => any`; parameters `props: { item: NavMenuOptionData; }`)

### NavMenuRoot

#### Props
Properties for the NavMenuRoot component.
- `modelValue`: The controlled value of the active item. Can be used as `v-model`. (type `string`; optional)
- `defaultValue`: The value of the item that should be active when initially rendered. (type `string`; optional)
- `dir`: The reading direction of the menu. (type `Direction`; optional)
- `orientation`: The orientation of the menu. (type `DataOrientation`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the submenu opens. (type `number`; default `200`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableClickTrigger`: If `true`, the menu cannot be opened by clicking a trigger. (type `boolean`; default `false`; optional)
- `disableHoverTrigger`: If `true`, the menu cannot be opened by hovering a trigger. (type `boolean`; default `false`; optional)
- `disablePointerLeaveClose`: If `true`, the menu will not close when the pointer leaves the content. (type `boolean`; default `false`; optional)
#### Emits
Events for the NavMenuRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)

### NavMenuSubContent

#### Props
Properties for the NavMenuSubContent component (the nested flyout surface).
- `sideOffset`: Distance in pixels between the sub trigger and the nested flyout. (type `number`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)

### NavMenuSubTrigger

#### Props
Properties for the NavMenuSubTrigger component (the trigger of a nested flyout).
- `disabled`: Whether the trigger is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### NavMenuTrigger

#### Props
Properties for the NavMenuTrigger component.
- `disabled`: Whether the trigger is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### NavMenuViewport

#### Props
Properties for the NavMenuViewport component (the shared floating surface).
- `align`: Align the viewport against the active trigger. (type `Align`; optional)
- `sideOffset`: Distance in pixels between the trigger and the viewport. (type `number`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)

## Notes

### Architecture

| Capability     | NavMenu (Popper-native)                                             |
| :------------- | :------------------------------------------------------------------ |
| floating model | single `PopperRoot` + viewport as `PopperPositioner`                |
| positioning    | Floating UI against the active trigger (dynamic ref)                |
| hover delay    | shared Popper hover machine (`delayDuration` / `skipDelayDuration`) |
| grace corridor | positioner's `useGraceArea` anchored on the nav                     |
| dismissal      | positioner's `usePopperDismiss` (Escape / outside)                  |
| value routing  | `pendingValue` slot on the shared root context                      |

### Runtime notes

1. **Hover timing** — the menu opens after `delayDuration` on hover; while open (or within `skipDelayDuration` of the last close) hovering another trigger switches instantly. `disablePointerLeaveClose` keeps the menu open when the pointer leaves the content.
2. **Click vs. hover** — a submenu opened by hover ignores the subsequent click (`hasPointerMoveOpenedRef` guard), preventing accidental toggling. Set `disableHoverTrigger: true` for a click-only experience.
3. **Controlled / uncontrolled** — with `modelValue`, internal writes only emit `update:modelValue`; highlight fully follows the prop.
4. **Focus handling** — the content participates in Tab navigation via a focus proxy; `Escape` returns focus to the active trigger.

## FAQ

### How does NavMenu differ from the retired NavigationMenu family?

NavMenu drops the shared measured-size viewport and per-item hover roots in favor of Popper's native single-root + positioner model: Floating UI positions the viewport, and the grace corridor / dismissal come from the positioner. It trades the old size/motion-direction transitions for a standard floating popup. `NavigationMenu` and `SNavigationMenu` were removed in v0.50.0 — see the [migration guide](/components/navigation-menu).

### How do I keep only click triggers?

Set `disableHoverTrigger: true` — hovering no longer opens submenus while clicks still toggle. For hover-only, set `disableClickTrigger: true`.

### Can a parent item be both a link and have a submenu?

Yes — give the item both `href` / `to` and `children`. The trigger then renders as a link; clicking an open link trigger dismisses the menu first.

## NavigationMenu (removed)

- Page URL: /components/navigation-menu
- Markdown URL: /components/navigation-menu.md
- Description: NavigationMenu was removed in v0.50.0 — SNavigationMenu and the whole navigation-menu family no longer ship. NavMenu is the single navigation-menu family; this page keeps the component/type mapping and the behavioral differences for one release cycle.

# NavigationMenu (removed in v0.50.0)

> **⚠️ Removed:** `NavigationMenu` / `SNavigationMenu` and the whole `navigation-menu` family are **gone in v0.50.0**. Nothing is exported any more — use [`NavMenu`](/components/nav-menu) instead.

The family was frozen for one release cycle and then removed inside the v0.50.0 breaking window, together with the date / table / form engine replacements. This page is kept for one release cycle so existing code has a single place to migrate from; it documents only the removal and the mapping to `NavMenu`.

## What was removed

| Surface                                                     | Status                                                |
| :---------------------------------------------------------- | :---------------------------------------------------- |
| `@soybeanjs/headless/navigation-menu` sub-path              | Removed — every `NavigationMenu*` primitive and type  |
| `NavigationMenu*` symbols in the headless root export       | Removed (and from the `Headless.*` namespaced export) |
| `SNavigationMenu` in `@soybeanjs/ui`                        | Removed — no styled counterpart is shipped            |
| `provideNavigationMenuUi`                                   | Removed — use `provideNavMenuUi`                      |
| Docs examples, component API data, changelog component page | Removed                                               |
| `ui/navigation-menu` registry item (`sbean`)                | Removed                                               |

## Migrating to NavMenu

[`NavMenu`](/components/nav-menu) models the same domain — site-level navigation with hover/click triggers, keyboard navigation, a positioned viewport, and a data-driven `items` API — but on a single shared Popper surface: one `PopperPositioner` whose reference switches to the active trigger, with hover timing driven by one shared state machine. Root props are largely isomorphic (`modelValue` / `defaultValue`, `orientation`, `dir`, `delayDuration`, `skipDelayDuration`, `disableClickTrigger`, `disableHoverTrigger`, `disablePointerLeaveClose`).

```diff
- import { SNavigationMenu } from '@soybeanjs/ui';
+ import { SNavMenu } from '@soybeanjs/ui';

- <SNavigationMenu :items="items" />
+ <SNavMenu :items="items" />
```

```diff
- import { NavigationMenuRoot, NavigationMenuItem } from '@soybeanjs/headless/navigation-menu';
+ import { NavMenuRoot, NavMenuItem } from '@soybeanjs/headless/nav-menu';
```

### Component mapping

| Removed                                                                              | NavMenu                                                   |
| :----------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| `SNavigationMenu` / `NavigationMenuCompact`                                          | `SNavMenu` / `NavMenuCompact`                             |
| `NavigationMenuRoot` / `List` / `Item` / `Trigger` / `Content` / `Link` / `Viewport` | same name with the `NavMenu` prefix                       |
| `NavigationMenuSubList`                                                              | `NavMenuSubTrigger` + `NavMenuSubContent`                 |
| `NavigationMenuIndicator`                                                            | — (the shared `NavMenu` viewport carries a `PopperArrow`) |
| `provideNavigationMenuUi`                                                            | `provideNavMenuUi`                                        |

### Type mapping

Every removed `NavigationMenu*` type has a `NavMenu*` counterpart with the same suffix: `NavigationMenuRootProps` → `NavMenuRootProps`, `NavigationMenuOptionData` → `NavMenuOptionData`, `NavigationMenuUiSlot` → `NavMenuUiSlot`, and so on.

### Behavioral differences

- **Submenu surfaces** — `NavigationMenu` rendered sub-items inside an indicator + viewport pair; `NavMenu` opens a nested flyout next to the item's trigger (`NavMenuSubTrigger` / `NavMenuSubContent`), with `sideOffset` available on both `NavMenuViewport` and `NavMenuSubContent`.
- **Indicator** — `NavMenu` has no separate indicator primitive; the arrow lives on the shared viewport and follows the active trigger.
- **Mount control** — `NavigationMenuRoot` exposed `unmountOnHide`; `NavMenu` instead honors `forceMount` on its content primitives.
- **UI slots** — the slot sets differ (the removed `NavigationMenuUiSlot` declared 19 slots, `NavMenuUiSlot` declares 20 including `subTrigger` / `subContent` / `positioner`); `class`, `size`, and the `ui` prop keep the same meaning.

## PageTabs

- Page URL: /components/page-tabs
- Markdown URL: /components/page-tabs.md
- Description: A tabbed interface designed for navigating between different pages or views. It supports features like closable tabs, context menus, and customizable styling.

# PageTabs

## Overview

A tabbed interface designed for navigating between different pages or views. It supports features like closable tabs, context menus, and customizable styling.

## Features

- **Data-driven compact composition** — `SPageTabs` delegates the whole structure to the headless generic `PageTabsCompact<T>`, which owns tab iteration, pin sorting, close semantics, context-menu wiring, and the default item body (icon + label + pin + close + indicator).
- **Controlled or uncontrolled state** — `modelValue` / `items` support `v-model` / `v-model:items` (controlled); omitting them falls back to internal state via `useControllableState`.
- **Closable tabs with async guard** — every non-pinned tab renders a close button; `beforeClose` may return `false` or a promise resolving to `false` to block closing. Closing the active tab activates the next (or previous) sibling; closing via keyboard `Backspace` and middle-click (`middleClickClose`) work out of the box.
- **Pin / unpin with auto-sorting** — pinned tabs sort to the front on any change (pinned group first, then normal tabs; `hidePinnedIcon` is display-only and never affects ordering); the inline pin button toggles pinned state and the context menu provides `Pin` / `Unpin`.
- **Drag-to-reorder** — with `draggable` enabled, tabs can be dragged horizontally to change their position. Reordering is zone-restricted, matching browser tab bars (Chrome / VS Code): tabs only reorder within their own zone — the pinned group first, then unpinned — so an unpinned tab halts at the pinned boundary in real time and never lands before pinned tabs. A tab item with an explicit `draggable: false` is locked in place: it cannot be dragged and it acts as a barrier, so no other tab can be inserted at its position (e.g. a home tab pinned to the very first slot). Dragging is driven by the headless `useSortableList` hook: the dragged tab keeps its own slot as the placeholder and follows the cursor with `transform` only, while the sibling tabs slide out of the way with FLIP; on drop the new order is applied (emitting `update:items`) and the dragged tab slides into its final slot. Keyboard sorting works too — focus a tab, press `Space` to pick it up, move it with the arrow keys, drop with `Space` / `Enter`, abort with `Escape`. `tabDragStart` / `tabDragMove` / `tabDragEnd` emit the live drag state `{ item, index }`.
- **Context-menu factory** — `menuFactory(tab, state)` receives the hovered tab plus a `PageTabsState` (close, closeLeft, closeRight, closeOther, closeAll, pin, unpin and their per-action `*Closable` booleans) to build custom menus; `selectContextMenu` emits the chosen action and tab.
- **Full keyboard support** — the `useRovingFocusGroup` hook provides arrow-key movement; `Enter` activates a tab, `Backspace` closes it, and `Space` picks a tab up for keyboard reordering.
- **Auto-scroll active tab** — `usePageTabsScroll` keeps the active tab horizontally centered (`scrollTo` smooth) and converts the vertical wheel into horizontal scrolling.
- **Three visual variants** — `variant` (`chrome` / `card` / `slider`) with per-variant indicators (chrome corner SVGs / slider underline) and `size` (xs…2xl) via the `pageTabsVariants` `scv()` recipe.
- **Six customization slots** — `item` (scoped `{ item, index, active, closable }`), `icon`, `label`, `indicator`, `pin-icon`, `close-icon`.
- **Localized accessibility text** — the close / pin buttons fall back to localized `aria-label`s (`closeTab` / `pinTab` / `unpinTab`) across 13 built-in languages, overridable per button via `aria-label`.
- **Headless composition** — `PageTabsRoot` / `PageTabsItem` / `PageTabsClose` / `PageTabsPin` / `PageTabsCompact` are exported from `@soybeanjs/headless/page-tabs` for fully custom styled builds.

## Usage

Usage examples for page-tabs are rendered on the site.

> `SPageTabs` delegates its tab management to headless `PageTabsCompact`. For unstyled, data-driven composition, import `PageTabsCompact` from `@soybeanjs/headless/page-tabs`.

## Demos

Interactive demos for page-tabs are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): PageTabs, PageTabsClose, PageTabsCompact, PageTabsCompactItem, PageTabsItem, PageTabsPin, PageTabsRoot.

### PageTabs

#### Props
Properties for the PageTabs component.
- `class`: root element class (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `PageTabsVariant`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<PageTabsUi>`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `menuFactory`: A factory function to generate context menu options for each tab. (type `((tab: T, state: PageTabsState) => PageTabsContextMenuOptionData[])`; optional)
- `beforeClose`: Callback invoked before closing the tab. Return `false` or a promise that resolves to `false` to prevent closing. (type `((value: string) => MaybePromise<boolean | void>)`; optional)
- `itemProps`: Per-slot class overrides for the component. (type `BaseProps`; optional)
- `pinProps`: Per-slot class overrides for the component. (type `BaseProps`; optional)
- `closeProps`: Per-slot class overrides for the component. (type `BaseProps`; optional)
- `contextMenuProps`: Additional props for the context menu component. (type `Omit<ContextMenuCompactProps<import("@/index").DefinedValue>, 'options'>`; optional)
- `modelValue`: The active tab value. (type `string`; optional)
- `middleClickClose`: Whether middle-clicking a tab closes it. (type `boolean`; optional)
- `draggable`: Whether tabs can be reordered by dragging. Tabs only reorder within their own zone — the pinned group always stays in front. A tab item with an explicit `draggable: false` is locked in place. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `currentTabStopId`: The controlled value of the current stop item. Can be bound as `v-model`. (type `string | null`; optional)
- `defaultCurrentTabStopId`: The value of the current stop item. Use when you do not need to control the state of the stop item. (type `string`; optional)
- `preventScrollOnEntryFocus`: When `true`, will prevent scrolling to the focus item when focused. (type `boolean`; optional)
#### Slots
Slots for the PageTabs component.
- `item`: Custom content for the default tab item body. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `icon`: Custom content for the tab icon. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `label`: Custom content for the tab label. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `indicator`: Custom content for the tab indicator. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `pin-icon`: Custom content for the pin icon. (type `(() => void) | undefined`)
- `close-icon`: Custom content for the close icon. (type `(() => void) | undefined`)

### PageTabsClose

#### Props
Properties for the PageTabsClose component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### PageTabsCompact

#### Props
Properties for the PageTabsCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `menuFactory`: A factory function to generate context menu options for each tab. (type `((tab: T, state: PageTabsState) => PageTabsContextMenuOptionData[])`; optional)
- `beforeClose`: Callback invoked before closing the tab. Return `false` or a promise that resolves to `false` to prevent closing. (type `((value: string) => MaybePromise<boolean | void>)`; optional)
- `itemProps`: Per-slot class overrides for the component. (type `BaseProps`; optional)
- `pinProps`: Per-slot class overrides for the component. (type `BaseProps`; optional)
- `closeProps`: Per-slot class overrides for the component. (type `BaseProps`; optional)
- `contextMenuProps`: Additional props for the context menu component. (type `Omit<ContextMenuCompactProps<import("@/index").DefinedValue>, 'options'>`; optional)
- `modelValue`: The active tab value. (type `string`; optional)
- `middleClickClose`: Whether middle-clicking a tab closes it. (type `boolean`; optional)
- `draggable`: Whether tabs can be reordered by dragging. Tabs only reorder within their own zone — the pinned group always stays in front. A tab item with an explicit `draggable: false` is locked in place. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `currentTabStopId`: The controlled value of the current stop item. Can be bound as `v-model`. (type `string | null`; optional)
- `defaultCurrentTabStopId`: The value of the current stop item. Use when you do not need to control the state of the stop item. (type `string`; optional)
- `preventScrollOnEntryFocus`: When `true`, will prevent scrolling to the focus item when focused. (type `boolean`; optional)
#### Slots
Slots for the PageTabsCompact component.
- `item`: Custom content for the default tab item body. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `icon`: Custom content for the tab icon. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `label`: Custom content for the tab label. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `indicator`: Custom content for the tab indicator. (type `((props: PageTabsCompactItemSlotProps<T>) => any) | undefined`)
- `pin-icon`: Custom content for the pin icon. (type `(() => void) | undefined`)
- `close-icon`: Custom content for the close icon. (type `(() => void) | undefined`)

### PageTabsCompactItem

#### Slot Props
Slot props for a compact page tab item.
- `item`: Current item data. (type `T`; required)
- `index`: Index of the current item. (type `number`; required)
- `selected`: Whether the current item is selected. (type `boolean`; required)
- `closable`: Whether the current item can be closed. (type `boolean`; required)

### PageTabsItem

#### Props
Properties for the PageTabsItem component.
- `value`: The unique value of the tab. (type `string`; required)
- `pinned`: Whether the tab is pinned. (type `boolean`; optional)
- `draggable`: Whether drag reordering is enabled for this tab. A non-draggable tab is locked in place: it cannot be dragged and other tabs cannot be dropped onto it. Pinned tabs reorder within the pinned zone only. (type `boolean`; optional)
- `index`: Index of the tab within `items`, used to build the drag payload. (type `number`; optional)

### PageTabsPin

#### Props
Properties for the PageTabsPin component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### PageTabsRoot

#### Props
Properties for the PageTabsRoot component.
- `modelValue`: The active tab value. (type `string`; optional)
- `middleClickClose`: Whether middle-clicking a tab closes it. (type `boolean`; optional)
- `draggable`: Whether tabs can be reordered by dragging. Tabs only reorder within their own zone — the pinned group always stays in front. A tab item with an explicit `draggable: false` is locked in place. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `currentTabStopId`: The controlled value of the current stop item. Can be bound as `v-model`. (type `string | null`; optional)
- `defaultCurrentTabStopId`: The value of the current stop item. Use when you do not need to control the state of the stop item. (type `string`; optional)
- `preventScrollOnEntryFocus`: When `true`, will prevent scrolling to the focus item when focused. (type `boolean`; optional)

## Notes

### Architecture and benchmark comparison

| Concern                                   | SoybeanUI                                        | Ant Design `Tabs`                   | Element Plus `Tabs`            | tags-view (vue-element-admin style) |
| :---------------------------------------- | :----------------------------------------------- | :---------------------------------- | :----------------------------- | :---------------------------------- |
| Headless / styled separation              | ✅ `@soybeanjs/headless/page-tabs` + `scv()`     | ❌ single package                   | ❌ single package              | ❌ custom per app                   |
| Data-driven compact API                   | ✅ generic `PageTabsCompact<T>` + `items`        | ✅ config-driven (items)            | ✅ config-driven               | ✅ per app                          |
| Controlled / uncontrolled                 | ✅ `modelValue`/`items` + `useControllableState` | ✅ `activeKey` / `defaultActiveKey` | ✅ `v-model`                   | —                                   |
| Closable + async guard                    | ✅ `beforeClose` (false / Promise\<false>)       | ✅ `onEdit` + `beforeChange`        | ✅ `closable` / `before-leave` | ✅ `before-close`                   |
| Pin / unpin + auto-sort                   | ✅ pinned tabs sort to front                     | ❌ (custom tabLabel)                | ❌                             | ✅ (per app, e.g. affix-tab)        |
| Drag-to-reorder                           | ✅ `draggable` + `tabDragStart/Move/End`         | ❌                                  | ❌                             | ✅ (per app)                        |
| Context menu (left/right/other/all close) | ✅ `menuFactory` + `PageTabsState`               | ❌ (`dropdownMenu` on `more` only)  | ❌                             | ✅ (per app)                        |
| Middle-click close                        | ✅ `middleClickClose`                            | ❌                                  | ❌                             | ✅ (per app)                        |
| Keyboard (roving focus + Enter/Backspace) | ✅ `useRovingFocusGroup`                         | ✅ arrows / Home / End              | ✅ arrows                      | ❌                                  |
| Auto-scroll active tab                    | ✅ centered `scrollTo` + wheel-to-horizontal     | ✅ `auto` on tabBar                 | ❌                             | ✅ (per app)                        |
| Variants                                  | ✅ `chrome`/`card`/`slider` × xs…2xl             | ✅ `line`/`card`/`editable-card`    | ✅ `card`/`border-card`        | —                                   |
| Localized `aria-label`                    | ✅ locale registry (13 langs)                    | partial                             | —                              | —                                   |
| Slots                                     | ✅ 6 typed slots                                 | ✅ `label`/`closeIcon`/…            | ✅ `label`/`icon`/…            | —                                   |

### Runtime considerations

1. **Pinned tabs are not closable** — `closable` derives from `!pinned`; pinned tabs render no close button, and middle-click / `Backspace` / context-menu close actions are disabled for them.
2. **Active-tab close fallback** — closing the active tab activates the next sibling, falling back to the previous one; closing the last tab clears `modelValue` to `''` (no tab active).
3. **Async `beforeClose`** — it may be synchronous or return a promise; only a resolved `false` blocks the close. The `close` event fires after the guard passes and the tab is removed.
4. **Pin sorting** — `sortTabs` reorders items as pinned → normal (stable, keeping the relative order within each group) and emits `update:items` when the order changes; in controlled mode the parent must accept the new order to see the reorder.
5. **Controlled vs. uncontrolled** — when `modelValue` / `items` props are provided, internal writes only emit `update:modelValue` / `update:items`; the DOM follows the props, so external changes re-render automatically.
6. **Context menu target** — hovering a tab (pointerenter) sets it as the context target and emits `contextmenu`; the menu itself renders from `menuFactory` only when it returns non-empty options.
7. **Drag-to-reorder scope** — drag reordering is a `PageTabsCompact`-level feature (`draggable`). Sorting is zone-restricted: tabs reorder within their own zone only (pinned → unpinned; all pinned tabs — including `hidePinnedIcon` ones — share one zone), so unpinned tabs can never be dragged in front of pinned ones — the real-time reorder is blocked at the boundary and `sortTabs` keeps the zone invariant. A tab item with an explicit `draggable: false` is fully locked: it cannot be dragged and is excluded from collision candidates, so no other tab can be dropped onto its position. In controlled mode (`v-model:items`) the parent must accept the reordered `update:items` to see the new order. Standalone `PageTabsRoot` / `PageTabsItem` composition has no drag support.
8. **Locale fallback** — close/pin `aria-label`s come from `useLocaleMessages`; missing keys fall back to the default English bundle; an explicit `aria-label` on the close/pin button wins.

## FAQ

### How do I prevent closing a tab?

Return `false` (or a promise that resolves to `false`) from `beforeClose`. The guard applies to the close button, middle-click, `Backspace`, and the context-menu close actions. For a pinned tab, just mark `pinned: true` — pinned tabs are never closable.

### Why are pinned tabs shown first?

Pinning is meant to keep important pages accessible; `sortTabs` moves pinned tabs (as one group, `hidePinnedIcon` included) in front of normal ones while keeping the relative order inside each group. If you pass `pinned` items in arbitrary order, the component reorders them on mount and emits `update:items` with the sorted array.

### Can I customize the context menu?

Yes — implement `menuFactory(tab, state)`. `state` exposes `close`, `closeLeft`, `closeRight`, `closeOther`, `closeAll`, `pin`, `unpin`, and the matching `*Closable` flags so you can disable irrelevant actions (e.g. "Close Left" on the first tab). Selecting an item runs its `action` and emits `selectContextMenu(menu, tab)`.

### How do I close the active tab gracefully?

Closing the active tab automatically activates the next sibling (or the previous one when the closed tab was last). If the last remaining tab is closed, `modelValue` becomes `''` and no tab is active.

### What keyboard shortcuts are supported?

Arrow keys move focus through tabs (roving focus), `Enter` activates the focused tab, and `Backspace` closes it (unless pinned or blocked by `beforeClose`). Middle-click also closes when `middleClickClose` is enabled.

### Can I build a fully custom page tabs?

Yes — compose `PageTabsRoot` / `PageTabsItem` / `PageTabsClose` / `PageTabsPin` / `PageTabsCompact` from `@soybeanjs/headless/page-tabs` and inject styles via `providePageTabsUi` (or `SPageTabs`'s `ui` prop). The `item` slot receives `{ item, index, active, closable }` scoped props for per-tab rendering.

### How do I enable drag-to-reorder?

Set `draggable` on `SPageTabs` (or `PageTabsCompact`). Tabs become horizontally draggable with a floating preview and smooth slide animation; the new order is written back through `v-model:items`. Like browser tab bars, reordering is zone-restricted: pinned tabs (including `hidePinnedIcon` ones) reorder among themselves at the front, and unpinned tabs cannot be dragged past the pinned group — they halt at the boundary in real time. To lock an individual tab (e.g. a home tab kept at the very first slot), set `draggable: false` on that item: it cannot be dragged and no other tab can be dropped onto its position.

## Pagination

- Page URL: /components/pagination
- Markdown URL: /components/pagination.md
- Description: Pagination is used for splitting up content or data into several pages, with a control for navigating to the next or previous page.

# Pagination

## Overview

Pagination is used for splitting up content or data into several pages, with a control for navigating to the next or previous page.

## Features

- **Data-driven compact composition** — `SPagination` delegates the whole structure to the headless `PaginationCompact`, which owns the page windowing, default content, and internal composition (root → list → page items / actions → ellipsis).
- **Controlled or uncontrolled page state** — `page` / `pageSize` support `v-model` (controlled), while `defaultPage` / `defaultPageSize` provide uncontrolled usage backed by `useControllableState`.
- **Smart page windowing** — `siblingCount` controls how many page buttons surround the current page; `showEdges: true` always pins the first and last page and renders single or double ellipsis depending on where the current page sits.
- **Boundary auto-disable** — prev/first are disabled on the first page and next/last on the last page; `disabled: true` disables the entire control and suppresses all interaction.
- **Four visual variants** — `variant` (`pure` / `solid` / `outline` / `soft`), `shape` (`rounded` / `square`), and `size` (xs…2xl) are applied through the `paginationVariants` `scv()` recipe.
- **`actionVariant`** — when enabled, the first/prev/next/last action buttons also take the current `variant` styling, which otherwise paints only the current page.
- **Eight customization slots** — `default` (list), `leading`, `trailing`, `first`, `prev`, `next`, `last`, and `ellipsis`; dynamic slot forwarding keeps every headless slot reachable from the styled wrapper.
- **Per-region props forwarding** — `listProps`, `listItemProps`, `ellipsisProps`, `firstProps`, `prevProps`, `nextProps`, `lastProps` forward attributes to each region.
- **Full ARIA semantics** — the root is a `nav`; the active page carries `aria-current="page"` and the selected state attribute; every button gets a localized `aria-label`.
- **Localized accessibility text** — action labels and the page label template come from the locale registry (`pageLabel` supports the `{value}` placeholder) across 13 built-in languages.
- **RTL support** — action icons are mirrored automatically via `rtl:[&>svg]:rotate-180`.
- **Headless composition** — `PaginationRoot` / `PaginationList` / `PaginationListItem` / `PaginationEllipsis` / `PaginationFirst` / `PaginationPrev` / `PaginationNext` / `PaginationLast` are exported from `@soybeanjs/headless/pagination` for fully custom styled builds.

## Usage

Usage examples for pagination are rendered on the site.

> `SPagination` delegates its page windowing to headless `PaginationCompact`. For unstyled, data-driven composition, import `PaginationCompact` from `@soybeanjs/headless/pagination`.

## Demos

Interactive demos for pagination are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (11): Pagination, PaginationButton, PaginationCompact, PaginationEllipsis, PaginationFirst, PaginationLast, PaginationList, PaginationListItem, PaginationNext, PaginationPrev, PaginationRoot.

### Pagination

#### Props
Properties for the Pagination component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: The custom ui class names (type `Partial<PaginationUi>`; optional)
- `size`: The size of the pagination (type `ThemeSize`; optional)
- `variant`: The variant of the pagination (type `PaginationVariant`; optional)
- `shape`: The shape of the pagination (type `PaginationShape`; optional)
- `actionVariant`: Whether the first/prev/next/last action buttons also use the `variant` styling, which otherwise only paints the current page (type `boolean`; optional)
- `showFirstOrLast`: Whether to show a first or last. (type `boolean`; optional)
- `listProps`: Properties forwarded to the list element. (type `PaginationListProps`; optional)
- `listItemProps`: Properties forwarded to the list item element. (type `PaginationListItemProps`; optional)
- `ellipsisProps`: Properties forwarded to the ellipsis element. (type `PaginationEllipsisProps`; optional)
- `firstProps`: Properties forwarded to the first element. (type `PaginationButtonProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `PaginationButtonProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `PaginationButtonProps`; optional)
- `lastProps`: Properties forwarded to the last element. (type `PaginationButtonProps`; optional)
- `page`: The controlled value of the current page. Can be bound as `v-model:page`. (type `number`; optional)
- `defaultPage`: The value of the page that should be active when initially rendered. Use when you do not need to control the value state. (type `number`; optional)
- `pageSize`: Number of items per page (type `number`; optional)
- `defaultPageSize`: The default value of `pageSize` when initially rendered. Use when you do not need to control the value state. (type `number`; default `10`; optional)
- `total`: Number of items in your list (type `number`; optional)
- `siblingCount`: Number of sibling should be shown around the current page (type `number`; optional)
- `disabled`: When `true`, prevents the user from interacting with item (type `boolean`; optional)
- `showEdges`: When `true`, always show first page, last page, and ellipsis (type `boolean`; optional)
#### Emits
Events for the Pagination component.
- `update:page`: Event handler called when the page value changes (type `[value: number]`; parameters `value: number`)
- `update:pageSize`: Event handler called when the page size value changes (type `[value: number]`; parameters `value: number`)
#### Slots
Slots for the Pagination component.
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `first`: Custom content for the first slot. (type `(() => any) | undefined`)
- `prev`: Custom content for the prev slot. (type `(() => any) | undefined`)
- `next`: Custom content for the next slot. (type `(() => any) | undefined`)
- `last`: Custom content for the last slot. (type `(() => any) | undefined`)
- `ellipsis`: Custom content for the ellipsis slot. (type `(() => any) | undefined`)

### PaginationButton

#### Props
Properties for the PaginationButton component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### PaginationCompact

#### Props
Properties for the PaginationCompact component.
- `showFirstOrLast`: Whether to show a first or last. (type `boolean`; optional)
- `listProps`: Properties forwarded to the list element. (type `PaginationListProps`; optional)
- `listItemProps`: Properties forwarded to the list item element. (type `PaginationListItemProps`; optional)
- `ellipsisProps`: Properties forwarded to the ellipsis element. (type `PaginationEllipsisProps`; optional)
- `firstProps`: Properties forwarded to the first element. (type `PaginationButtonProps`; optional)
- `prevProps`: Properties forwarded to the prev element. (type `PaginationButtonProps`; optional)
- `nextProps`: Properties forwarded to the next element. (type `PaginationButtonProps`; optional)
- `lastProps`: Properties forwarded to the last element. (type `PaginationButtonProps`; optional)
- `page`: The controlled value of the current page. Can be bound as `v-model:page`. (type `number`; optional)
- `defaultPage`: The value of the page that should be active when initially rendered. Use when you do not need to control the value state. (type `number`; optional)
- `pageSize`: Number of items per page (type `number`; optional)
- `defaultPageSize`: The default value of `pageSize` when initially rendered. Use when you do not need to control the value state. (type `number`; default `10`; optional)
- `total`: Number of items in your list (type `number`; optional)
- `siblingCount`: Number of sibling should be shown around the current page (type `number`; optional)
- `disabled`: When `true`, prevents the user from interacting with item (type `boolean`; optional)
- `showEdges`: When `true`, always show first page, last page, and ellipsis (type `boolean`; optional)
#### Emits
Events for the PaginationCompact component.
- `update:page`: Event handler called when the page value changes (type `[value: number]`; parameters `value: number`)
- `update:pageSize`: Event handler called when the page size value changes (type `[value: number]`; parameters `value: number`)
#### Slots
Slots for the PaginationCompact component.
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `first`: Custom content for the first slot. (type `(() => any) | undefined`)
- `prev`: Custom content for the prev slot. (type `(() => any) | undefined`)
- `next`: Custom content for the next slot. (type `(() => any) | undefined`)
- `last`: Custom content for the last slot. (type `(() => any) | undefined`)
- `ellipsis`: Custom content for the ellipsis slot. (type `(() => any) | undefined`)

### PaginationEllipsis

- No documented props, emits, slots, or slot props were available.

### PaginationFirst

- No documented props, emits, slots, or slot props were available.

### PaginationLast

- No documented props, emits, slots, or slot props were available.

### PaginationList

- No documented props, emits, slots, or slot props were available.

### PaginationListItem

#### Props
Properties for the PaginationListItem component.
- `value`: Value for the page (type `number`; required)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### PaginationNext

- No documented props, emits, slots, or slot props were available.

### PaginationPrev

- No documented props, emits, slots, or slot props were available.

### PaginationRoot

#### Props
Properties for the PaginationRoot component.
- `page`: The controlled value of the current page. Can be bound as `v-model:page`. (type `number`; optional)
- `defaultPage`: The value of the page that should be active when initially rendered. Use when you do not need to control the value state. (type `number`; optional)
- `pageSize`: Number of items per page (type `number`; optional)
- `defaultPageSize`: The default value of `pageSize` when initially rendered. Use when you do not need to control the value state. (type `number`; default `10`; optional)
- `total`: Number of items in your list (type `number`; optional)
- `siblingCount`: Number of sibling should be shown around the current page (type `number`; optional)
- `disabled`: When `true`, prevents the user from interacting with item (type `boolean`; optional)
- `showEdges`: When `true`, always show first page, last page, and ellipsis (type `boolean`; optional)
#### Emits
Events for the PaginationRoot component.
- `update:page`: Event handler called when the page value changes (type `[value: number]`; parameters `value: number`)
- `update:pageSize`: Event handler called when the page size value changes (type `[value: number]`; parameters `value: number`)

## Notes

### Architecture and benchmark comparison

| Concern                      | SoybeanUI                                                        | shadcn-vue `Pagination`                  | Ant Design `Pagination`            | Element Plus `Pagination`    |
| :--------------------------- | :--------------------------------------------------------------- | :--------------------------------------- | :--------------------------------- | :--------------------------- |
| Headless / styled separation | ✅ `@soybeanjs/headless/pagination` + `scv()`                    | ❌ single package                        | ❌ single package                  | ❌ single package            |
| Compact data-driven API      | ✅ `PaginationCompact` + 8 typed slots                           | ✅ `Pagination` + `PaginationItem` parts | ✅ config-driven (total, current)  | ✅ layout / components       |
| Controlled / uncontrolled    | ✅ `page`/`defaultPage`, `pageSize`/`defaultPageSize`            | ✅ `v-model`                             | ✅ `current` / `defaultCurrent`    | ✅ `v-model`                 |
| Ellipsis + pinned edges      | ✅ `showEdges` + automatic single/double ellipsis                | ✅ `showEdges` on `PaginationItem`       | ✅ `showLessItems` / auto ellipsis | ✅ `pager-count`             |
| Boundary auto-disable        | ✅ prev/first at page 1, next/last at last page                  | ✅ `disabled` on parts                   | ✅ `prevIcon`/`nextIcon` handling  | ✅ auto                      |
| Disable entire control       | ✅ `disabled`                                                    | ✅                                       | ✅ `disabled`                      | ✅ `disabled`                |
| Selected page styling        | ✅ `data-[selected]` + `actionVariant`                           | ✅ `data-[active]`                       | ✅ `current` item class            | ✅ `active`                  |
| Localized `aria-label`       | ✅ locale registry (13 langs, `{value}` interpolation)           | hard-coded / `aria-label` prop           | partial                            | —                            |
| Variant system               | ✅ `pure`/`solid`/`outline`/`soft` × `rounded`/`square` × xs…2xl | ✅ size only                             | ✅ `size`                          | ✅ `small`/`default`/`large` |
| Per-region props forwarding  | ✅ 7 props groups                                                | ✅ `asChild` per part                    | ✅ `itemRender`                    | ✅ per-part props            |
| RTL icon mirroring           | ✅ automatic                                                     | —                                        | ✅                                 | ✅                           |

### Runtime considerations

1. **Window math** — `getRange` shows both ellipsis only when the current page is far enough from both ends (`leftSiblingIndex > firstPageIndex + 2` and `rightSiblingIndex < lastPageIndex - 2`); near either edge it degrades to a single ellipsis, otherwise the full range renders.
2. **`total` pages** — `pageCount` is `Math.max(1, Math.ceil(total / pageSize))`, so an empty list still yields one page; a `page` above `pageCount` renders the last window without crashing.
3. **Controlled state sync** — when bound with `v-model:page`, clicking an item emits `update:page`; the internal window follows the prop, so external page changes (e.g. after a fetch) re-render the correct window automatically.
4. **`showFirstOrLast`** — setting it to `false` removes the first/last buttons but keeps prev/next; page count math is unaffected.
5. **`actionVariant`** — it only lets the action buttons reuse the `variant` recipe; the selected page item always uses the `data-[selected]` styling regardless of this flag.
6. **Locale fallback** — button labels come from `useLocaleMessages`; missing keys fall back to the default English bundle; `pageLabel` supports the `{value}` placeholder via `interpolate`.
7. **A11y output** — the active page renders with `aria-current="page"` and the `data-selected` attribute; disabled actions keep `disabled` so they are skipped by assistive technology and keyboard navigation.

## FAQ

### When do the ellipsis appear?

With `showEdges: true`, the first and last page are always pinned. The current page sits at either edge of the window → one ellipsis; deep in the middle (e.g. page 50 of 100) → two ellipsis with `siblingCount` pages on each side. With `showEdges: false`, only the current window renders and no ellipsis is shown.

### How do I make pagination controlled vs. uncontrolled?

Pass `page` (and optionally `pageSize`) together with an `@update:page` handler, or simply use `v-model:page`. For uncontrolled usage, rely on `defaultPage` / `defaultPageSize` and let the component manage its own state.

### What is `actionVariant` for?

By default the first/prev/next/last action buttons use a neutral action style. When `actionVariant` is `true`, those buttons also take the `variant` styling — the same one the current page uses (e.g. a solid primary look) — which is useful when the active page visually merges with the action buttons.

### Why are prev/first disabled on the first page?

The first/prev buttons disable automatically when `page === 1` and next/last when `page === pageCount`, preventing out-of-range navigation. Set `disabled: true` to disable the whole control.

### Can I fully customize the buttons?

Yes — the `first`, `prev`, `next`, `last`, `ellipsis`, `leading`, and `trailing` slots replace the default content, and `firstProps` / `prevProps` / `nextProps` / `lastProps` forward attributes (including styles) to the respective regions. The default list slot receives scoped `{ page, pageCount }`-aware items through the headless list.

### How is accessibility handled?

The root is a `nav` landmark; every button carries a localized `aria-label` (the page buttons use the `pageLabel` template, e.g. "Page 5"); the active page is announced with `aria-current="page"`; disabled buttons use the native `disabled` attribute and are skipped by assistive technology.

### Can I build a fully custom pagination?

Yes — compose `PaginationRoot` / `PaginationList` / `PaginationListItem` / `PaginationEllipsis` / `PaginationFirst` / `PaginationPrev` / `PaginationNext` / `PaginationLast` from `@soybeanjs/headless/pagination` and inject styles via `providePaginationUi` (or `SPagination`'s `ui` prop).

## PalettePicker

- Page URL: /components/palette-picker
- Markdown URL: /components/palette-picker.md
- Description: SPalettePicker is a color picker that produces a full palette from a single base color. Its modelValue is a ColorValue — either a Tailwind palette key + level (e.g. indigo.500), a simple palette key (black / white / transparent …), or a raw custom color (hsl(...) / oklch(...)).

# PalettePicker

## Overview

`SPalettePicker` is a color picker that produces a full palette from a single base color. Its `modelValue` is a [`ColorValue`](/overview/theming) — either a Tailwind palette key + level (e.g. `indigo.500`), a simple palette key (`black` / `white` / `transparent` …), or a raw custom color (`hsl(...)` / `oklch(...)`).

## Usage

Usage examples for palette-picker are rendered on the site.

## Features

- 🎯 `modelValue` is a `ColorValue`, directly consumable by the theme system
- 🎨 Pick a Tailwind palette key, then a level, for a clean `key.level` value
- ⚫ Or pick a simple palette key (`black`, `white`, `transparent` …)
- 🌐 Built-in palette color names are localized (follow the current locale)
- ✨ **Custom** mode: pick any color with a `ColorPicker`, see the generated palette, click any level to select/highlight it, and toggle **Recommended palette** to snap the display to the nearest Tailwind palette
- 📤 Emits `paletteChange` with the full generated palette so consumers can register it as a theme preset
- 🌈 `format` (`hsl` / `oklch`) controls how the custom color is serialized

## Demos

Interactive demos for palette-picker are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): PalettePicker.

### PalettePicker

#### Props
Properties for the PalettePicker component.
- `size`: Visual size of the component. (type `ThemeSize`; default `'md'`; optional)
- `format`: Output color space used to serialize the custom color into a `ColorValue`. (type `ColorFormat`; default `'hsl'`; optional)

## Notes

### Custom mode & theme presets

The theme engine's custom presets must be registered. When the user edits a custom color, listen to `paletteChange` and feed `payload.palette` into your registration flow; the emitted `payload.value` is the committed `ColorValue`.

### Recommended palette

In custom mode the generated palette levels are clickable — clicking a level highlights it (like the built-in level selector). When **Recommended palette** is enabled, `generateNearestPalette` snaps the palette to the nearest built-in Tailwind palette, and picking a level commits that palette's `key.level` value. When disabled, the raw custom color is committed in the configured `format`, and clicking a level only highlights it.

## Password

- Page URL: /components/password
- Markdown URL: /components/password.md
- Description: A password input field with a toggle button to show/hide the entered value. Use it for login forms, sign-up forms, or any sensitive credential entry. It composes the input family base with a visibility switch, and supports clearable mode. For non-sensitive text use SInput.

# Password

## Overview

A password input field with a toggle button to show/hide the entered value. Use it for login forms, sign-up forms, or any sensitive credential entry. It composes the input family base with a visibility switch, and supports clearable mode. For non-sensitive text use `SInput`.

## Usage

Usage examples for password are rendered on the site.

## Features

- 📏 6 sizes: xs, sm, md, lg, xl, 2xl (inherited from the input base)
- 👁 Show/hide toggle with i18n `aria-label` and `aria-pressed` semantics
- 🎛 Controlled / uncontrolled `visible` state (`v-model:visible` + `defaultVisible`)
- 🧹 Clearable mode with an i18n `aria-label` clear button
- 🔒 `disabled` / `readonly` guards across input, toggle, and clear elements
- 📋 Native form submission via a proxied hidden input when `name` is set
- 🧩 Custom `visible` slot for a bespoke toggle button
- ♿ Full accessibility support — toggle naming, pressed state, axe-clean

## Demos

Interactive demos for password are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (2): Password, PasswordCompact.

### Password

#### Props
Properties for the Password component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<PasswordUi>`; optional)
- `visible`: Controlled password visibility. (type `boolean`; optional)
- `defaultVisible`: The initial visibility state when it is not controlled. (type `boolean`; default `false`; optional)
- `visibleProps`: Properties forwarded to the visible element. (type `ButtonProps`; optional)
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputControlProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `InputClearProps`; optional)
- `defaultValue`: The default value of the input (type `string`; optional)
- `modelValue`: The controlled value of the input (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the Password component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `update:visible`: Emitted when the visible state changes. (type `[visible: boolean]`; parameters `visible: boolean`)
#### Slots
Slots for the Password component.
- `leading`: Custom content for the leading slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
- `clear`: Custom content for the clear slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
- `visible`: Custom content for the visible slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)

### PasswordCompact

#### Props
Properties for the PasswordCompact component.
- `visible`: Controlled password visibility. (type `boolean`; optional)
- `defaultVisible`: The initial visibility state when it is not controlled. (type `boolean`; default `false`; optional)
- `visibleProps`: Properties forwarded to the visible element. (type `ButtonProps`; optional)
- `inputRef`: The function to set the input element. (type `((el: HTMLInputElement) => void)`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `controlProps`: Properties forwarded to the control element. (type `InputControlProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `InputClearProps`; optional)
- `defaultValue`: The default value of the input (type `string`; optional)
- `modelValue`: The controlled value of the input (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `rootProps`: Properties forwarded to the root element (type `BaseProps`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
#### Emits
Events for the PasswordCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `update:visible`: Emitted when the visible state changes. (type `[visible: boolean]`; parameters `visible: boolean`)
#### Slots
Slots for the PasswordCompact component.
- `leading`: Custom content for the leading slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
- `clear`: Custom content for the clear slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
- `visible`: Custom content for the visible slot. (type `((props: PasswordCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the PasswordCompact component.
- `modelValue`: Current model value. (type `string`; optional)
- `clear`: Clear handler. (type `() => void`; required)
- `visible`: Whether the password is visible. (type `boolean`; required)
- `toggle`: Toggle password visibility. (type `() => void`; required)

## Notes

### Architecture and benchmark differences

SoybeanUI builds the password input by reusing the input family base: `PasswordCompact` composes `InputRoot` / `InputControl` / `InputClear` and adds a default `visible` slot backed by `useControllableState`. The styled layer extends `inputVariants` with a `visible` slot override styled as a mini icon button. This mirrors the headless/styled split of reka-ui and shadcn, differing from single-package libraries such as Element Plus.

| Capability                          | SoybeanUI | reka-ui `PasswordInput` | shadcn | Element Plus `el-input` |
| :---------------------------------- | :-------: | :---------------------: | :----: | :---------------------: |
| headless/styled split               |    ✅     |            —            |   —    |            —            |
| Controlled / uncontrolled `visible` |    ✅     |           ✅            |   —    |            —            |
| Show/hide toggle (icon)             |    ✅     |           ✅            |   ✅   |           ✅            |
| i18n toggle label                   |    ✅     |            —            |   —    |           ✅            |
| `aria-pressed` semantics            |    ✅     |            —            |   —    |            —            |
| Clearable mode                      |    ✅     |            —            |   ✅   |           ✅            |
| `disabled` / `readonly` guards      |    ✅     |           ✅            |   ✅   |           ✅            |
| Size variants (xs…2xl)              |    ✅     |            —            |   —    |            —            |
| Custom `visible` slot               |    ✅     |            —            |   —    |            —            |
| Form proxying (hidden input)        |    ✅     |            —            |   —    |            —            |

### Cautions

- The `type` prop is intentionally overridden by the visibility state (`text` when visible, `password` otherwise); a user-provided `type` is not honored.
- The `visible` toggle button renders with `type="button"` to prevent accidental native form submission.
- Cursor position and password-manager compatibility are guaranteed by the native input contract.

## FAQ

### How do I default the password to visible?

Pass `defaultVisible` (uncontrolled) or bind `visible` with `v-model:visible` (controlled).

### How do I customize the toggle button?

Use the `visible` slot. It receives `modelValue`, `visible`, `clear`, and `toggle` props for full control.

### How do I make the field clearable?

Pass `clearable`. The clear button clears the value and emits `clear`; it is disabled together with `disabled` / `readonly`.

### Why does my `type` prop get ignored?

Password fields must switch between `text` and `password` to toggle visibility. The component owns this switch, so a user-provided `type` is overridden by design.

## Popconfirm

- Page URL: /components/popconfirm
- Markdown URL: /components/popconfirm.md
- Description: A confirmation box component based on Popper, used for lightweight secondary confirmation operations. SPopconfirm combines the headless PopconfirmCompact (built on the popper primitives) with the popconfirmVariants style recipe (13 slots, 6 sizes × 4 types).

# Popconfirm

## Overview

A confirmation box component based on `Popper`, used for lightweight secondary confirmation operations. `SPopconfirm` combines the headless `PopconfirmCompact` (built on the popper primitives) with the `popconfirmVariants` style recipe (13 slots, 6 sizes × 4 types).

Use it for a quick inline confirm (delete, destructive action) next to the trigger. For a richer blocking confirmation use `dialog`; for an unobtrusive hint use `tooltip`.

## Usage

Usage examples for popconfirm are rendered on the site.

## Features

- 🧩 Built on `Popper` — inherits placement, arrow, portal, dismissable and focus behavior
- 🎨 4 types — `type="error"`/`"success"`/`"warning"`/`"info"` drive the leading icon and color
- 🏷️ Title + description + content — `title`/`description`/`content` props or the matching slots
- 🔘 Confirm/cancel — `confirmText`/`cancelText` (localized from `dialog.confirm`/`dialog.cancel`); `showCancel` defaults to `onlyWarning`
- 🖼️ Icon toggle — `showIcon` renders the type icon; `showArrow` renders the popper arrow
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ♿ Accessible — popup exposes `role="dialog"` labelled by the trigger, focus-managed, `axe-core` clean in the browser e2e
- 🔒 Disabled — `disabled` blocks the trigger from opening the popconfirm

## Component family

- `SPopconfirm` (styled) — the entry wrapper; `popconfirmVariants` recipe with dynamic slot forwarding
- `PopconfirmCompact` (headless) — the aggregated composite built on `PopperRoot`/`PopperTrigger`/`PopperPositioner`/`PopperPopup`
- `PopconfirmHeader` / `PopconfirmContent` / `PopconfirmFooter` (headless) — layout sections
- `PopconfirmTitle` / `PopconfirmDescription` (headless) — the title/description
- `PopconfirmConfirm` / `PopconfirmCancel` (headless) — footer `<button>`s, emit `confirm`/`cancel`

## Playground

Interactive demos for popconfirm are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (17): Popconfirm, PopconfirmAnchor, PopconfirmArrow, PopconfirmCancel, PopconfirmClose, PopconfirmCompact, PopconfirmConfirm, PopconfirmContent, PopconfirmDescription, PopconfirmFooter, PopconfirmHeader, PopconfirmPopup, PopconfirmPortal, PopconfirmPositioner, PopconfirmRoot, PopconfirmTitle, PopconfirmTrigger.

### Popconfirm

#### Props
Properties for the Popconfirm component.
- `class`: class of popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<PopconfirmUi>`; optional)
- `type`: Type. (type `PopconfirmType`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `content`: Content. (type `string`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; default `true`; optional)
- `showIcon`: Whether to show an icon. (type `boolean`; default `true`; optional)
- `confirmText`: The text of the confirm button. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `cancelText`: The text of the cancel button. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showCancel`: Determines whether the cancel button is shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopconfirmTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopconfirmPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopconfirmPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopconfirmPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopconfirmArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopconfirmCloseProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `PopconfirmHeaderProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `PopconfirmTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `PopconfirmDescriptionProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `PopconfirmContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `PopconfirmFooterProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `PopconfirmConfirmProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `PopconfirmCancelProps`; optional)
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the Popconfirm component.
- `update:open`: No description. (type `[value: boolean, reason: PopperOpenChangeReason]`; parameters `value: boolean, reason: PopperOpenChangeReason`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
- `confirm`: Emitted when confirm occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `cancel`: Emitted when cancel occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the Popconfirm component.
- `default`: Custom content for the default slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)

### PopconfirmAnchor

#### Props
Properties for the PopconfirmAnchor component.
- `reference`: No description. (type `ReferenceElement`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### PopconfirmArrow

- No documented props, emits, slots, or slot props were available.

### PopconfirmCancel

#### Props
Properties for the PopconfirmCancel component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the PopconfirmCancel component.
- `cancel`: Emitted when cancel occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### PopconfirmClose

#### Props
Properties for the PopconfirmClose component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the PopconfirmClose component.
- `close`: Emitted when close occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### PopconfirmCompact

#### Props
Properties for the PopconfirmCompact component.
- `type`: Type. (type `PopconfirmType`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `title`: Title text rendered by the component. (type `string`; optional)
- `description`: Description text rendered by the component. (type `string`; optional)
- `content`: Content. (type `string`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; default `true`; optional)
- `showIcon`: Whether to show an icon. (type `boolean`; default `true`; optional)
- `confirmText`: The text of the confirm button. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `cancelText`: The text of the cancel button. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showCancel`: Determines whether the cancel button is shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopconfirmTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopconfirmPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopconfirmPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopconfirmPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopconfirmArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopconfirmCloseProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `PopconfirmHeaderProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `PopconfirmTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `PopconfirmDescriptionProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `PopconfirmContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `PopconfirmFooterProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `PopconfirmConfirmProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `PopconfirmCancelProps`; optional)
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the PopconfirmCompact component.
- `update:open`: No description. (type `[value: boolean, reason: PopperOpenChangeReason]`; parameters `value: boolean, reason: PopperOpenChangeReason`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
- `confirm`: Emitted when confirm occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `cancel`: Emitted when cancel occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the PopconfirmCompact component.
- `default`: Custom content for the default slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: PopconfirmCompactBaseSlotProps) => any) | undefined`)

### PopconfirmConfirm

#### Props
Properties for the PopconfirmConfirm component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the PopconfirmConfirm component.
- `confirm`: Emitted when confirm occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### PopconfirmContent

- No documented props, emits, slots, or slot props were available.

### PopconfirmDescription

- No documented props, emits, slots, or slot props were available.

### PopconfirmFooter

- No documented props, emits, slots, or slot props were available.

### PopconfirmHeader

- No documented props, emits, slots, or slot props were available.

### PopconfirmPopup

- No documented props, emits, slots, or slot props were available.

### PopconfirmPortal

- No documented props, emits, slots, or slot props were available.

### PopconfirmPositioner

#### Props
Properties for the PopconfirmPositioner component.
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the PopconfirmPositioner component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)

### PopconfirmRoot

#### Props
Properties for the PopconfirmRoot component.
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the PopconfirmRoot component.
- `update:open`: No description. (type `[value: boolean, reason: PopperOpenChangeReason]`; parameters `value: boolean, reason: PopperOpenChangeReason`)

### PopconfirmTitle

- No documented props, emits, slots, or slot props were available.

### PopconfirmTrigger

#### Props
Properties for the PopconfirmTrigger component.
- `trigger`: No description. (type `PopperTriggerType`; optional)
- `reference`: No description. (type `ReferenceElement`; optional)
- `openDelay`: No description. (type `number`; optional)
- `closeDelay`: No description. (type `number`; optional)
- `skipDelayDuration`: No description. (type `number`; optional)
- `pressOpenDelay`: No description. (type `number`; optional)
- `openOnFocus`: No description. (type `boolean`; optional)
- `focusOpenDelay`: Open delay applied to focus-driven opens. Defaults to `openDelay`; set `0` to open instantly on focus (Tooltip semantics). (type `number`; default `inherit from `openDelay``; optional)
- `focusVisibleOnly`: When `true`, focus-driven opening only responds to keyboard/programmatic focus (`:focus-visible`), ignoring pointer-derived focus. (type `boolean`; default `false`; optional)
- `ariaMode`: How the trigger references its popup for assistive technology. - `controls`: `aria-expanded` + `aria-controls` (expandable widgets: popover / menu) - `describedby`: `aria-describedby` while open (tooltip-like descriptions) - `none`: no popup-reference attributes (type `PopperTriggerAriaMode`; default `'controls'`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`PopconfirmCompact` composes the popper trigger/positioner/popup with a confirm-style header, content and footer, while every primitive stays style-free and only the UI wrapper injects the `popconfirmVariants` classes. This mirrors radix-ui/shadcn-ui's headless split. Ant Design, Element Plus, Mantine and Naive UI ship a single styled popconfirm with `title`/`description`/`okText`/`cancelText`/`onConfirm` props; SoybeanUI additionally exposes per-slot `*Props`, a `size` scale, a `type` color/icon system, and localized action labels.

| Capability               | SoybeanUI | shadcn/ui | Ant Design Popconfirm | Element Plus Popconfirm | Mantine Popconfirm | Naive UI Popconfirm |
| :----------------------- | :-------: | :-------: | :-------------------: | :---------------------: | :----------------: | :-----------------: |
| Built on Popper          |    ✅     |    ✅     |           —           |            —            |         —          |          —          |
| Headless/styled split    |    ✅     |    ✅     |           —           |            —            |         —          |          —          |
| Type icon + color        |    ✅     |     —     |           —           |           ✅            |         —          |          —          |
| Title + description      |    ✅     |    ✅     |          ✅           |           ✅            |         ✅         |         ✅          |
| Localized confirm/cancel |    ✅     |     —     |           —           |            —            |         —          |          —          |
| Sizes (6)                |    ✅     |     —     |           —           |            —            |         —          |          —          |
| Placement (popper)       |    ✅     |    ✅     |          ✅           |           ✅            |         ✅         |         ✅          |

`—` = unsupported or a different interaction model.

### Cautions

- `modal` defaults to `false` for popconfirm (unlike dialog), so it does not block outside interaction or lock body scroll.
- `showCancel` defaults to `'onlyWarning'` — the cancel button appears only for `type="warning"`. Pass an explicit boolean to override.
- `confirmText`/`cancelText` default to the localized `dialog.confirm`/`dialog.cancel` messages; override per instance.
- The popup renders `role="dialog"` and is labelled by the trigger; provide a `title` so the dialog has a clear accessible name.
- Confirm/cancel emit `confirm`/`cancel` events; the popup dismisses after either action (subject to your own `beforeClose` handling in the parent).

### Roadmap

N/A — popconfirm is feature-complete for the current parity set.

## FAQ

### How do I show a title, description and content?

Pass `title`/`description`/`content` props or the matching slots:

```vue

  <template #trigger><SButton danger>Delete</SButton></template>

```

### How do I set the type and icon?

Use `type` (`error`/`success`/`warning`/`info`) and toggle `show-icon`:

```vue

  <template #trigger><SButton>Delete</SButton></template>

```

### How do I customize the action labels?

Set `confirm-text`/`cancel-text`, and control the cancel button with `show-cancel`:

```vue

  <template #trigger><SButton>Delete</SButton></template>

```

### How do I control the open state?

Bind `open` with `v-model` or use `defaultOpen`:

```vue

  <template #trigger><SButton>Delete</SButton></template>

```

### How do I disable the trigger?

Set `disabled` to block opening:

```vue

  <template #trigger><SButton>Delete</SButton></template>

```

## Popover

- Page URL: /components/popover
- Markdown URL: /components/popover.md
- Description: Displays rich content in a portal, triggered by a button. SPopover combines the headless PopoverRoot/PopoverTrigger/PopoverPositioner/PopoverPopup/PopoverArrow/PopoverClose primitive family (built on the shared Popper + dialog-style dismissable/focus layers) with the popoverVariants style recipe (5 slots, 6 sizes).

# Popover

## Overview

Displays rich content in a portal, triggered by a button. `SPopover` combines the headless `PopoverRoot`/`PopoverTrigger`/`PopoverPositioner`/`PopoverPopup`/`PopoverArrow`/`PopoverClose` primitive family (built on the shared `Popper` + dialog-style dismissable/focus layers) with the `popoverVariants` style recipe (5 slots, 6 sizes).

Use a popover for contextual, non-critical rich content (menus of actions, settings, help). For navigation menus use `dropdown-menu`; for a small hover hint use `tooltip`; for a blocking confirmation use `popconfirm` or `dialog`.

## Usage

Usage examples for popover are rendered on the site.

## Features

- 🧩 Headless/styled split — `PopoverCompact` aggregates the popper positioner, popup, arrow and close; `SPopover` only injects styles and forwards slots/events
- 🎯 Placement — full popper `placement` control (12 directions) with collision avoidance and side-aware slide animations
- 🎭 Modal toggle — `modal` controls outside-pointer blocking, `useHideOthers`, body scroll lock and focus trapping
- 🔽 Arrow — `showArrow` renders a positioned arrow; configurable via `arrowProps`
- ❌ Closable — optional `close` slot with a built-in `lucide:x` icon; Escape and outside interaction dismiss
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ♿ Accessible — `role="dialog"`, focus trap + loop, `aria-label`d close button, `axe-core` zero violations

## Component family

- `SPopover` (styled) — the entry wrapper; `popoverVariants` recipe with dynamic slot forwarding
- `PopoverRoot` (headless) — the state owner; `open` via `useControllableState`, `dir`/`modal`/`disabled`, provides the popper root
- `PopoverTrigger` (headless) — a `Button` that toggles the popover
- `PopoverPositioner` / `PopoverPositionerImpl` (headless) — the focus-trapped, dismissable, positioned surface (built on `PopperPositioner`)
- `PopoverPopup` (headless) — the popup body
- `PopoverArrow` (headless) — the popper arrow
- `PopoverClose` (headless) — the close `<button>`, emits `close` and toggles `open`
- `PopoverCompact` (headless) — the aggregated composite; composes positioner/popup/arrow/close and exposes the slots

## Demos

Interactive demos for popover are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (10): Popover, PopoverAnchor, PopoverArrow, PopoverClose, PopoverCompact, PopoverPopup, PopoverPortal, PopoverPositioner, PopoverRoot, PopoverTrigger.

### Popover

#### Props
Properties for the Popover component.
- `class`: class of popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<PopoverUi>`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopoverPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopoverArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the Popover component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
#### Slots
Slots for the Popover component.
- `default`: Custom content for the default slot. (type `((props: { open: boolean; close: () => void; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `(() => any) | undefined`)
- `close`: Custom content for the close slot. (type `(() => any) | undefined`)

### PopoverAnchor

- No documented props, emits, slots, or slot props were available.

### PopoverArrow

- No documented props, emits, slots, or slot props were available.

### PopoverClose

#### Props
Properties for the PopoverClose component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the PopoverClose component.
- `close`: Emitted when close occurs. (type `[PointerEvent]`; parameters `PointerEvent`)

### PopoverCompact

#### Props
Properties for the PopoverCompact component.
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopoverTriggerProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `PopoverPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `PopoverPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `PopoverPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopoverArrowProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `PopoverCloseProps`; optional)
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the PopoverCompact component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
#### Slots
Slots for the PopoverCompact component.
- `default`: Custom content for the default slot. (type `((props: { open: boolean; close: () => void; }) => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `(() => any) | undefined`)
- `close`: Custom content for the close slot. (type `(() => any) | undefined`)

### PopoverPopup

- No documented props, emits, slots, or slot props were available.

### PopoverPortal

- No documented props, emits, slots, or slot props were available.

### PopoverPositioner

#### Props
Properties for the PopoverPositioner component.
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the PopoverPositioner component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)

### PopoverRoot

#### Props
Properties for the PopoverRoot component.
- `dir`: No description. (type `Direction`; optional)
- `open`: No description. (type `boolean`; optional)
- `defaultOpen`: No description. (type `boolean`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: No description. (type `boolean`; optional)
#### Emits
Events for the PopoverRoot component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)

### PopoverTrigger

#### Props
Properties for the PopoverTrigger component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`PopoverCompact` owns the positioner/popup/arrow/close composition while every primitive stays style-free and only the UI wrapper injects the `popoverVariants` classes. This mirrors radix-ui/shadcn-ui's headless/styled split, built on the shared `Popper` primitives. Ant Design, Element Plus, Mantine and Naive UI ship a single styled popover with `placement`/`trigger`/`width` props; SoybeanUI additionally exposes per-slot `*Props`, a `size` scale, an arrow toggle, and a `modal` mode the single-package popovers generally lack.

| Capability            | SoybeanUI | shadcn/ui | Ant Design Popover | Element Plus Popover | Mantine Popover | Naive UI Popover |
| :-------------------- | :-------: | :-------: | :----------------: | :------------------: | :-------------: | :--------------: |
| Headless/styled split |    ✅     |    ✅     |         —          |          —           |        —        |        —         |
| Popper placement (12) |    ✅     |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |
| Arrow                 |    ✅     |    ✅     |         —          |          —           |        —        |        —         |
| Modal mode            |    ✅     |    ✅     |         —          |          —           |        —        |        —         |
| Close button          |    ✅     |    ✅     |         —          |          —           |        —        |        —         |
| Sizes (6)             |    ✅     |     —     |         —          |          —           |        —        |        —         |
| Focus trap + loop     |    ✅     |    ✅     |         —          |          —           |        —        |        —         |

`—` = unsupported or a different interaction model.

### Cautions

- `PopoverRoot` defaults to modal (`true`): opening it blocks outside pointer events and locks body scroll. Pass `modal={false}` for a lightweight, non-blocking popover.
- The popup is rendered through a `Portal` (teleported to `document.body`); position it inside a relatively-positioned ancestor only with `portalProps: { disabled: true }`.
- `showArrow` renders an arrow; `arrowProps` can override its position/classes.
- Provide a `close` slot to show the close control; it defaults to a `lucide:x` icon.
- Unlike `tooltip`, the popover does not auto-dismiss on pointer-leave; it stays open until dismissed.

### Roadmap

N/A — popover is feature-complete for the current parity set.

## FAQ

### How do I position the popover?

Use `placement` (from popper), e.g. `top`, `bottom-start`, `right-end`:

```vue

  <template #trigger><SButton>Info</SButton></template>

```

### How do I add a close button?

Provide the `close` slot:

```vue

  <template #trigger><SButton>More</SButton></template>
  <template #close>Dismiss</template>

```

### How do I make a non-blocking popover?

Set `modal={false}`:

```vue

  <template #trigger><SButton>Open</SButton></template>

```

### How do I control the open state?

Bind `open` with `v-model` or use `defaultOpen`:

```vue

  <template #trigger><SButton>Open</SButton></template>

```

## Progress

- Page URL: /components/progress
- Markdown URL: /components/progress.md
- Description: A progress indicator for determinate or indeterminate task completion. SProgress combines the headless ProgressRoot/ProgressIndicator primitives with the progressVariants style recipe, and SProgressCircle offers a circular variant via progressCircleVariants. Both share an imperative API (progress.start()/done()) surfaced through SProgressProvider.

# Progress

## Overview

A progress indicator for determinate or indeterminate task completion. `SProgress` combines the headless `ProgressRoot`/`ProgressIndicator` primitives with the `progressVariants` style recipe, and `SProgressCircle` offers a circular variant via `progressCircleVariants`. Both share an imperative API (`progress.start()`/`done()`) surfaced through `SProgressProvider`.

Use it for uploads, downloads, multi-step flows, or top-of-page loading bars. Prefer `spinner` for an indefinite wait, and `skeleton` for reserving content space before it loads.

## Usage

Usage examples for progress are rendered on the site.

## Features

- 🧩 Headless/styled split — `ProgressRoot`/`ProgressIndicator` own state, `role="progressbar"` ARIA and derived values; `SProgress` injects `progressVariants`
- 🔢 Determinate / indeterminate — `modelValue` shows a concrete value; omitting it shows an indeterminate bar
- 🎨 8 colors — `ThemeColor` values on the indicator
- 📐 6 sizes — xs–2xl `size`
- ⭕ Circle variant — `SProgressCircle` for a circular gauge with configurable `strokeWidth`
- 🏷️ Custom label — `getValueLabel`/`getValueText` shape the `aria-label`/`aria-valuetext`
- ⚡ Imperative API — `progress.start()`/`set()`/`inc()`/`done()` etc. via `SProgressProvider` for top-of-page loading
- ♿ Accessible — `role="progressbar"` with `aria-valuemin/max/now` and a localized `aria-label` fallback

## Component family

- `SProgress` (styled) — the linear wrapper; `progressVariants` recipe
- `SProgressCircle` (styled) — the circular wrapper; `progressCircleVariants` recipe
- `SProgressProvider` (styled) — mounts the imperative progress layer
- `ProgressRoot` (headless) — the state owner; normalizes `modelValue`/`max`, derives state/value percent, renders `role="progressbar"`
- `ProgressIndicator` (headless) — the fill; sizes via CSS vars/transform per `dir`
- `ProgressCircleCompact` / `ProgressCompact` (headless) — the aggregated composites
- `progress` (imperative) — the shared `start`/`set`/`inc`/`done`/`configure` controller

## Demos

Interactive demos for progress are rendered on the site.

## Circle Progress

```vue
<script setup lang="ts">
import { SProgressCircle } from '@soybeanjs/ui';
</script>

<template>
  <SProgressCircle :model-value="72" size="xl">
    <template #default="{ valuePercent }">{{ Math.round(valuePercent ?? 0) }}%</template>
  </SProgressCircle>
</template>
```

`SProgressCircle` supports the same props, emits, slot props, and `Ui` type as `SProgress`, and adds the following prop:

## Progress Provider

Mount `SProgressProvider` once near your app root before calling the imperative `progress(...)` API. `SConfigProvider` mounts it automatically, so most applications can call `progress` directly.

```vue
<script setup lang="ts">
import { SButton, SProgressProvider, progress } from '@soybeanjs/ui';

const handleClick = () => {
  progress.start();

  window.setTimeout(() => {
    progress.done();
  }, 1200);
};
</script>

<template>
  <SProgressProvider />
  <SButton @click="handleClick">Start loading</SButton>
</template>
```

### `progress` Methods

| Method         | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| `start()`      | Show the progress bar with the default start position and delay, then start trickling. |
| `set(value)`   | Set the raw progress value between `minimum` and `maximum`.                            |
| `inc()`        | Increment the current progress value.                                                  |
| `dec()`        | Decrement the current progress value.                                                  |
| `trickle()`    | Apply one automatic increment step.                                                    |
| `done()`       | Complete the progress bar and hide it after the configured delay.                      |
| `configure()`  | Update the shared progress options.                                                    |
| `pause()`      | Pause automatic trickling.                                                             |
| `resume()`     | Resume automatic trickling.                                                            |
| `remove()`     | Hide the progress bar immediately.                                                     |
| `reset()`      | Reset the shared progress state and options.                                           |
| `isStarted()`  | Check whether the progress flow is active.                                             |
| `isRendered()` | Check whether a progress provider is currently mounted.                                |
| `promise()`    | Bind the progress lifecycle to a promise or promise factory.                           |

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (8): Progress, ProgressCircle, ProgressCircleCompact, ProgressCircleSvg, ProgressCompact, ProgressIndicator, ProgressProvider, ProgressRoot.

### Progress

#### Props
Properties for the Progress component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ProgressUi>`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `ProgressIndicatorProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `modelValue`: The controlled progress value. Can be bind as `v-model`. (type `number | null`; optional)
- `max`: The maximum progress value. (type `number`; optional)
- `getValueLabel`: The accessible label of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `getValueText`: The accessible text of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Progress component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: number | null | undefined]`; parameters `value: number | null | undefined`)
- `update:max`: Emitted when the max value changes. (type `[value: number]`; parameters `value: number`)
#### Slots
Slots for the Progress component.
- `default`: Custom content for the default slot. (type `((props: ProgressSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the Progress component family.
- `modelValue`: Current model value. (type `number | null | undefined`; required)
- `max`: Max used by the component. (type `number`; required)
- `progressState`: Progress state used by the component. (type `'loading' | 'indeterminate' | 'complete'`; required)
- `valuePercent`: Current progress percentage. (type `number | null`; required)

### ProgressCircle

#### Props
Properties for the ProgressCircle component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ProgressUi>`; optional)
- `strokeWidth`: Stroke width. (type `number`; optional)
- `circleSvgProps`: Properties forwarded to the ProgressCircleSvg component. (type `ProgressCircleSvgProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `modelValue`: The controlled progress value. Can be bind as `v-model`. (type `number | null`; optional)
- `max`: The maximum progress value. (type `number`; optional)
- `getValueLabel`: The accessible label of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `getValueText`: The accessible text of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ProgressCircle component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: number | null | undefined]`; parameters `value: number | null | undefined`)
- `update:max`: Emitted when the max value changes. (type `[value: number]`; parameters `value: number`)
#### Slots
Slots for the ProgressCircle component.
- `default`: Custom content for the default slot. (type `((props: ProgressSlotProps) => any) | undefined`)

### ProgressCircleCompact

#### Props
Properties for the ProgressCircleCompact component.
- `strokeWidth`: Stroke width. (type `number`; optional)
- `circleSvgProps`: Properties forwarded to the ProgressCircleSvg component. (type `ProgressCircleSvgProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `modelValue`: The controlled progress value. Can be bind as `v-model`. (type `number | null`; optional)
- `max`: The maximum progress value. (type `number`; optional)
- `getValueLabel`: The accessible label of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `getValueText`: The accessible text of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ProgressCircleCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: number | null | undefined]`; parameters `value: number | null | undefined`)
- `update:max`: Emitted when the max value changes. (type `[value: number]`; parameters `value: number`)
#### Slots
Slots for the ProgressCircleCompact component.
- `default`: Custom content for the default slot. (type `((props: ProgressSlotProps) => any) | undefined`)

### ProgressCircleSvg

#### Props
Properties for the ProgressCircleSvg component.
- `strokeWidth`: Stroke width. (type `number`; optional)

### ProgressCompact

#### Props
Properties for the ProgressCompact component.
- `indicatorProps`: Properties forwarded to the indicator element. (type `ProgressIndicatorProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `modelValue`: The controlled progress value. Can be bind as `v-model`. (type `number | null`; optional)
- `max`: The maximum progress value. (type `number`; optional)
- `getValueLabel`: The accessible label of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `getValueText`: The accessible text of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ProgressCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: number | null | undefined]`; parameters `value: number | null | undefined`)
- `update:max`: Emitted when the max value changes. (type `[value: number]`; parameters `value: number`)
#### Slots
Slots for the ProgressCompact component.
- `default`: Custom content for the default slot. (type `((props: ProgressSlotProps) => any) | undefined`)

### ProgressIndicator

#### Props
Properties for the ProgressIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ProgressProvider

#### Props
Properties for the ProgressProvider component.
- `direction`: Direction. (type `Direction`; optional)
- `minimum`: Minimum. (type `number`; optional)
- `maximum`: Maximum. (type `number`; optional)
- `easing`: Easing. (type `string`; optional)
- `speed`: Speed. (type `number`; optional)
- `trickle`: Whether trickle. (type `boolean`; optional)
- `trickleSpeed`: Trickle speed. (type `number`; optional)

### ProgressRoot

#### Props
Properties for the ProgressRoot component.
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `modelValue`: The controlled progress value. Can be bind as `v-model`. (type `number | null`; optional)
- `max`: The maximum progress value. (type `number`; optional)
- `getValueLabel`: The accessible label of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `getValueText`: The accessible text of the current progress value. (type `((value: number | null, max: number) => string)`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ProgressRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: number | null | undefined]`; parameters `value: number | null | undefined`)
- `update:max`: Emitted when the max value changes. (type `[value: number]`; parameters `value: number`)

## Notes

### Architecture and benchmark differences

`ProgressRoot` owns the value normalization (`getValidMax`/`getValidModelValue`), state derivation (`indeterminate`/`loading`/`complete`) and the `role="progressbar"` ARIA contract, while the primitives stay style-free and only the UI wrapper injects the recipe classes. This mirrors shadcn/ui's headless/styled split, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single config-driven progress. SoybeanUI's distinguishing feature is the `nprogress`-style imperative controller (`progress.start()`/`done()`) and the `SProgressCircle` gauge, both of which the single-package libraries handle as separate components or omit.

| Capability                      | SoybeanUI | shadcn/ui | Ant Design Progress | Element Plus Progress | Mantine Progress | Naive UI Progress |
| :------------------------------ | :-------: | :-------: | :-----------------: | :-------------------: | :--------------: | :---------------: |
| Linear progress                 |    ✅     |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |
| Circle progress                 |    ✅     |     —     |         ✅          |          ✅           |        ✅        |        ✅         |
| Indeterminate                   |    ✅     |     —     |         ✅          |          ✅           |        ✅        |        ✅         |
| Imperative API (`start`/`done`) |    ✅     |     —     |          —          |           —           |        —         |         —         |
| Color variants (8)              |    ✅     |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |
| Size variants (6)               |    ✅     |     —     |          —          |           —           |        —         |         —         |
| `role="progressbar"` ARIA       |    ✅     |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |
| Custom value label              |    ✅     |     —     |          —          |          ✅           |        ✅        |        ✅         |

`—` = unsupported or a different interaction model.

### Cautions

- For a determinate value the `aria-label` falls back to the localized percentage label (`45%`); the localized `progress.ariaLabel` only applies to indeterminate progress. Set an explicit `aria-label` to override either.
- Indeterminate progress (no `modelValue`) has no `aria-valuenow`; its `data-state` is `indeterminate`.
- The imperative `progress` API requires a mounted `SProgressProvider` — `SConfigProvider` mounts one automatically.
- `SProgressCircle` stroke width is clamped between 1 and `viewbox/4`; pass `strokeWidth` for a thinner/thicker gauge.
- The indicator uses `transform` + CSS vars and swaps direction under RTL via `dir`.

### Roadmap

No blocking gaps identified for the core progress API.

## FAQ

### How do I show a determinate value?

Pass `model-value`:

```vue

```

### How do I show an indeterminate bar?

Omit `model-value`:

```vue

```

### How do I use the top-of-page loading bar?

Mount `SProgressProvider` (or rely on `SConfigProvider`) and call the imperative API:

```vue
<script setup>
const load = () => {
  progress.start();
  setTimeout(() => progress.done(), 1200);
};
</script>
<template><SButton @click="load">Load</SButton></template>
```

### How do I customize the announced label?

Pass `get-value-label`/`get-value-text` or an explicit `aria-label`:

```vue

```

### Circle or linear?

Use `SProgressCircle` for a compact gauge in a dashboard/stat, and `SProgress` for a full-width linear indicator or the top-of-page bar.

## Radio Group

- Page URL: /components/radio-group
- Markdown URL: /components/radio-group.md
- Description: A set of checkable radio buttons where no more than one button can be checked at a time. It ships as a data-driven group and a card variant with icon/description content, both built on roving-focus keyboard navigation. Use it for single-choice from a small, mutually exclusive set; when multiple values are allowed, use SCheckboxGroup; when the option set is too large to scan at once, prefer SSelect.

# Radio Group

## Overview

A set of checkable radio buttons where no more than one button can be checked at a time. It ships as a data-driven group and a card variant with icon/description content, both built on roving-focus keyboard navigation. Use it for single-choice from a small, mutually exclusive set; when multiple values are allowed, use `SCheckboxGroup`; when the option set is too large to scan at once, prefer `SSelect`.

## Usage

Usage examples for radio-group are rendered on the site.

## Features

- ☑️ Single-choice model — `modelValue` / `defaultValue` with both controlled and uncontrolled modes
- ⌨️ Roving-focus keyboard navigation — Arrow keys move and check, Enter/Space select, optional `loop`
- 🏷 Accessible labels — `RadioGroupLabel` wires `for` to each control's `id`
- 📋 Native form proxy — a visually hidden input carries the current value with `name` / `required`
- 🃏 Card variant (`SRadioGroupCard`) with icon, label, and description content
- 🎨 6 sizes, 8 colors, and dot/outline variants via `radioGroupVariants`
- 📊 Data-driven `RadioGroupCompact` / `RadioGroupCardCompact` aggregation in headless
- ♿ `role="radiogroup"` + `role="radio"` with `aria-checked` / `data-state` dual reflection, axe-clean

## Component family

- `SRadioGroup` - data-driven radio group with dot/outline variants
- `SRadioGroupCard` - card radio group with icon, label, and description

## Demos

Interactive demos for radio-group are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (9): RadioGroup, RadioGroupCard, RadioGroupCardCompact, RadioGroupCompact, RadioGroupControl, RadioGroupIndicator, RadioGroupItem, RadioGroupLabel, RadioGroupRoot.

### RadioGroup

#### Props
Properties for the RadioGroup component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `variant`: Visual variant of the component. (type `RadioGroupVariant`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<RadioGroupUi>`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `itemProps`: Properties forwarded to the item element. (type `RadioGroupItemProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `RadioGroupControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `RadioGroupIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `RadioGroupLabelProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T['value']`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the radio group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the RadioGroup component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: T | null]`; parameters `payload: T | null`)

### RadioGroupCard

#### Props
Properties for the RadioGroupCard component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `variant`: Visual variant of the component. (type `RadioGroupVariant`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<RadioGroupCardUi>`; optional)
- `contentProps`: Properties forwarded to the content element. (type `BaseProps`; optional)
- `textContentProps`: Properties forwarded to the text content element. (type `BaseProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `BaseProps`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `itemProps`: Properties forwarded to the item element. (type `RadioGroupItemProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `RadioGroupControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `RadioGroupIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `RadioGroupLabelProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T['value']`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the radio group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the RadioGroupCard component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: T | null]`; parameters `payload: T | null`)
#### Slots
Slots for the RadioGroupCard component.
- `description`: Slot for rendering custom description content within the radio card. (type `((props: { item: T; }) => any) | undefined`)

### RadioGroupCardCompact

#### Props
Properties for the RadioGroupCard component.
- `contentProps`: Properties forwarded to the content element. (type `BaseProps`; optional)
- `textContentProps`: Properties forwarded to the text content element. (type `BaseProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `BaseProps`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `itemProps`: Properties forwarded to the item element. (type `RadioGroupItemProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `RadioGroupControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `RadioGroupIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `RadioGroupLabelProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T['value']`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the radio group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the RadioGroupCardCompact component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: T | null]`; parameters `payload: T | null`)
#### Slots
Slots for the RadioGroupCompact component.
- `description`: Slot for rendering custom description content within the radio card. (type `((props: { item: T; }) => any) | undefined`)

### RadioGroupCompact

#### Props
Properties for the RadioGroupCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `itemProps`: Properties forwarded to the item element. (type `RadioGroupItemProps`; optional)
- `controlProps`: Properties forwarded to the control element. (type `RadioGroupControlProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `RadioGroupIndicatorProps`; optional)
- `labelProps`: Properties forwarded to the label element. (type `RadioGroupLabelProps`; optional)
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T['value']`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the radio group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the RadioGroupCompact component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: T | null]`; parameters `payload: T | null`)

### RadioGroupControl

#### Props
Properties for the RadioGroupControl component.
- `id`: Id of the element (type `string`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### RadioGroupIndicator

#### Props
Properties for the RadioGroupIndicator component.
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### RadioGroupItem

#### Props
Properties for the RadioGroupItem component.
- `value`: The value given as data when submitted with a `name`. (type `boolean | import("@/index").DefinedValue`; required)
- `disabled`: When `true`, prevents the user from interacting with the radio item. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the RadioGroupItem component.
- `select`: Event handler called when the radio item is selected (type `[event: RadioSelectEvent]`; parameters `event: RadioSelectEvent`)

### RadioGroupLabel

- No documented props, emits, slots, or slot props were available.

### RadioGroupRoot

#### Props
Properties for the RadioGroupRoot component.
- `modelValue`: The controlled value of the radio item to check. Can be bound as `v-model`. (type `T | null`; optional)
- `defaultValue`: The value of the radio item that should be checked when initially rendered. Use when you do not need to control the state of the radio items. (type `T`; optional)
- `disabled`: When `true`, prevents the user from interacting with radio items. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the radio group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the RadioGroupRoot component.
- `update:modelValue`: Event handler called when the radio group value changes (type `[payload: T | null]`; parameters `payload: T | null`)

## Notes

### Architecture and benchmark differences

SoybeanUI builds the radio group from headless `RadioGroupRoot` (`useControllableState` + `useRovingFocusGroup`) → `RadioGroupItem` (checked derivation + `VisuallyHiddenInput` form proxy) → `RadioGroupControl` (`Button` base + `role="radio"` + `aria-checked`/`data-state`, focus-derived selection) → `RadioGroupIndicator` (`usePresence` conditional mount) → `RadioGroupLabel` (`for` ↔ control `id`). `RadioGroupCompact` / `RadioGroupCardCompact` own item iteration and default composition while the UI wrappers only inject variant classes. The `scv()` recipes `radioGroupVariants` / `radioGroupCardVariants` declare 6 sizes, 8 colors, and dot/outline variants.

| Capability                      | SoybeanUI | Ant Design `Radio` | Element Plus `Radio` | Mantine `Radio` | Naive UI `Radio` | shadcn `RadioGroup` |
| :------------------------------ | :-------: | :----------------: | :------------------: | :-------------: | :--------------: | :-----------------: |
| headless/styled split           |    ✅     |         —          |          —           |        —        |        —         |         ✅          |
| Single-choice exclusive         |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |         ✅          |
| Roving-focus keyboard nav       |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |         ✅          |
| Controlled/uncontrolled         |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |         ✅          |
| Card variant (icon/description) |    ✅     |         —          |          —           |        —        |        —         |          —          |
| `button` variant                |    ➕     |         ✅         |          ✅          |        —        |        —         |          —          |
| `Radio.Button` composite        |    ➕     |         ✅         |          —           |        —        |        —         |          —          |
| Form proxy / `name` submit      |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |         ✅          |
| Axe-clean (group + card)        |    ✅     |         —          |          —           |        —        |        —         |          —          |

### Cautions

- Arrow-key selection commits through a focus-derived click on the control, so it flows through the same `radio.select` / `update:modelValue` path as mouse clicks.
- The form proxy renders when a `name` is present on a `form`-classed root; pair it with a native `<form>` or the `SForm` integration.
- `select` is a cancellable custom event — call `event.preventDefault()` to veto the value change.
- Enter is wired explicitly to the select handler (matching the checkbox family); Space relies on the native button click behavior.

## FAQ

### How does keyboard navigation work?

The group uses roving focus: one radio is tabbable, Arrow keys move focus (and check the focused radio), Enter/Space select. Set `loop` to cycle from last to first and vice versa.

### Controlled or uncontrolled?

Pass `modelValue` with `v-model` for a controlled value; pass `defaultValue` to let the group own its state internally. Both are supported via `useControllableState`.

### How do I submit the selected value with a form?

Give the group a `name`; inside a `form`-classed root a visually hidden input carries the current value so native form submission picks it up.

### What is the difference between `SRadioGroup` and `SCheckboxGroup`?

`SRadioGroup` enforces single choice — selecting one radio unchecks the others; `SCheckboxGroup` allows multiple checked values. Use radio for mutually exclusive options.

## Rating

- Page URL: /components/rating
- Markdown URL: /components/rating.md
- Description: A star-rating component built on a multi-slot headless core: RatingRoot provides the slider context, state, and keyboard handling, while each RatingItem renders a single star. Supports controlled and uncontrolled modes, half-star precision, clear-on-repeat-click, read-only and disabled states, horizontal/vertical orientation, RTL direction, and native form integration through a visually hidden input. Use it whenever users need to express a graded preference—product reviews, feedback surveys, or skill self-assessment.

# Rating

## Overview

A star-rating component built on a multi-slot headless core: `RatingRoot` provides the slider context, state, and keyboard handling, while each `RatingItem` renders a single star. Supports controlled and uncontrolled modes, half-star precision, clear-on-repeat-click, read-only and disabled states, horizontal/vertical orientation, RTL direction, and native form integration through a visually hidden input. Use it whenever users need to express a graded preference—product reviews, feedback surveys, or skill self-assessment.

## Usage

Usage examples for rating are rendered on the site.

## Features

- 🎚 `modelValue` / `defaultValue` — controlled and uncontrolled modes backed by `useControllableState`
- ⭐ `max` (default 5) drives the star count; each `RatingItem` is generated from context
- ½ `allowHalf` enables half-star precision; pointer position and arrow-key steps resolve to 0.5 increments
- ♻️ `allowClear` resets the value to 0 when the current item is clicked again
- ⌨️ Keyboard operable — ArrowUp/Right increments, ArrowDown/Left decrements, Home resets to 0, End sets to max
- ♿ `role="slider"` with full `aria-valuenow/min/max/valuetext/orientation/readonly/disabled/label` reflection
- 🧭 `orientation` (horizontal/vertical) and `dir` (ltr/rtl) drive layout and ARIA orientation
- 🎨 `ratingVariants` (6 sizes) + `ratingItemVariants` (8 colors × 2 variants × 6 sizes); default color `warning`, default variant `filled`
- 🧩 `icon` slot exposes `{ index, value, state }` (`state` is `'full' | 'half' | 'empty'`) for custom star rendering
- 📝 Form integration via `VisuallyHiddenInput` when `name` is provided
- 🌐 Localized ARIA — `rating.ariaLabel`, `rating.starN` (`{count} of {max} stars`), `rating.empty`
- 🚫 `readonly` + `disabled` states with guarded pointer and keyboard handling

## Demos

Interactive demos for rating are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (3): Rating, RatingItem, RatingRoot.

### Rating

#### Props
Properties for the Rating component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `RatingVariant`; optional)
- `modelValue`: The controlled value of the rating. Can be bound as `v-model`. (type `number`; optional)
- `defaultValue`: The initial value of the rating when uncontrolled. (type `number`; optional)
- `max`: The maximum rating value (number of items). (type `number`; optional)
- `allowHalf`: Whether half-star precision is allowed. (type `boolean`; optional)
- `allowClear`: Whether clicking the current value clears the rating to 0. (type `boolean`; optional)
- `readonly`: Whether the rating is read-only (focusable but not interactive). (type `boolean`; optional)
- `disabled`: Whether the rating is disabled (inert). (type `boolean`; optional)
- `orientation`: The orientation of the rating. (type `DataOrientation`; optional)
- `dir`: The reading direction of the rating. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Rating component.
- `update:modelValue`: Event handler called when the rating value changes. (type `[value: number]`; parameters `value: number`)
- `hoverChange`: Event handler called when the hover preview value changes. `null` when the pointer leaves. (type `[value: number | null]`; parameters `value: number | null`)
- `valueCommit`: Event handler called when a rating interaction is committed (click or keyboard). (type `[value: number]`; parameters `value: number`)

### RatingItem

#### Props
Properties for the RatingItem component.
- `index`: The zero-based index of the item within the rating. (type `number`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### RatingRoot

#### Props
Properties for the RatingRoot component.
- `modelValue`: The controlled value of the rating. Can be bound as `v-model`. (type `number`; optional)
- `defaultValue`: The initial value of the rating when uncontrolled. (type `number`; optional)
- `max`: The maximum rating value (number of items). (type `number`; optional)
- `allowHalf`: Whether half-star precision is allowed. (type `boolean`; optional)
- `allowClear`: Whether clicking the current value clears the rating to 0. (type `boolean`; optional)
- `readonly`: Whether the rating is read-only (focusable but not interactive). (type `boolean`; optional)
- `disabled`: Whether the rating is disabled (inert). (type `boolean`; optional)
- `orientation`: The orientation of the rating. (type `DataOrientation`; optional)
- `dir`: The reading direction of the rating. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the RatingRoot component.
- `update:modelValue`: Event handler called when the rating value changes. (type `[value: number]`; parameters `value: number`)
- `hoverChange`: Event handler called when the hover preview value changes. `null` when the pointer leaves. (type `[value: number | null]`; parameters `value: number | null`)
- `valueCommit`: Event handler called when a rating interaction is committed (click or keyboard). (type `[value: number]`; parameters `value: number`)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the rating into headless `RatingRoot` (slider context, `useControllableState`, keyboard navigation, ARIA reflection, half-step pointer resolution, `VisuallyHiddenInput` form binding) and headless `RatingItem` (renders each star from context, exposes `state` for slot-driven icons). The UI wrapper `SRating` injects `ratingVariants` and `ratingItemVariants` classes via the standard multi-slot `provide*Ui` / `useUiContext` pattern; state and visuals stay decoupled through `data-[state=...]` selectors. Compared with AntD `Rate`, Element Plus `el-rate`, Mantine `Rating`, and Naive UI `n-rate`, SoybeanUI is the only benchmarked library with a headless/styled split, RTL support, vertical orientation, and native form integration; shadcn ships no rating component.

| Capability              | SoybeanUI |   Ant Design   |  Element Plus  |    Mantine     |  Naive UI  | shadcn |
| :---------------------- | :-------: | :------------: | :------------: | :------------: | :--------: | :----: |
| headless/styled split   |    ✅     |       —        |       —        |       —        |     —      |   —    |
| Controlled/uncontrolled |    ✅     |       ✅       |       ✅       |       ✅       |     ✅     |   —    |
| Half-star precision     |    ✅     |       ✅       |       ✅       | ✅ (fractions) |     ✅     |   —    |
| Allow clear             |    ✅     |       ✅       |       ✅       |       ✅       |     ✅     |   —    |
| Read-only mode          |    ✅     |       ✅       |       ✅       |       ✅       |     ✅     |   —    |
| Custom icon (slot)      |    ✅     | ✅ (character) | ✅ (iconClass) |       ✅       |     ✅     |   —    |
| Keyboard navigation     |    ✅     |       —        |       —        |       ✅       |     —      |   —    |
| RTL support             |    ✅     |       —        |       —        |       —        |     —      |   —    |
| Vertical orientation    |    ✅     |       —        |       —        |       ✅       |     —      |   —    |
| Form integration        |    ✅     |       —        |       —        |       ✅       |     —      |   —    |
| Color/size variants     |    ✅     |      size      |      size      |      size      | size/color |   —    |

### Cautions

- The root element carries `role="slider"`; do not add `role="img"` or any other conflicting role to child items.
- Half-star precision depends on the pointer position within a single item; on touch devices, consider increasing the hit area so users can reliably target the half region.
- `allowClear` only fires when the clicked item matches the current value—clicking any other item changes the value normally.
- The `icon` slot receives `state` (`'full'` / `'half'` / `'empty'`); style custom icons with `data-[state=...]` selectors or conditional rendering.

## FAQ

### Controlled or uncontrolled?

Pass `modelValue` with `v-model` for a controlled value, or `defaultValue` to let the rating own its state internally. Both are supported via `useControllableState`.

### How do I use half-star precision?

Set `allowHalf` to `true`. Arrow keys then step by 0.5, and pointer position within an item determines whether the step resolves to a half or a full star.

### How do I customize the icon?

Use the `icon` slot and read the `state` prop: `<template #icon="{ state }">...</template>`. The slot also receives `index` and `value` if you need position-aware rendering.

### How do I clear the rating?

Set `allowClear` to `true`. Clicking the item that matches the current value resets the rating to 0; clicking any other item behaves normally.

## ScrollArea

- Page URL: /components/scroll-area
- Markdown URL: /components/scroll-area.md
- Description: A custom scroll container that keeps native scrolling behavior while rendering styled scrollbars for vertical and horizontal overflow.

# ScrollArea

## Overview

A custom scroll container that keeps native scrolling behavior while rendering styled scrollbars for vertical and horizontal overflow.

## Features

- **Native scroll engine** — scrolls with the browser's native performance while the native scrollbar is hidden.
- **Five visibility modes** — `type="auto"` (visible while overflow), `"always"` (always visible), `"hover"` (visible on hover), `"scroll"` (transiently visible while scrolling), and `"glimpse"` (a brief glimpse on hover).
- **Customizable hide delay** — `scrollHideDelay` (default 600ms) controls how long transient scrollbars (`scroll` / `glimpse`) stay visible.
- **Horizontal and vertical scrollbars** — independent `ScrollAreaScrollbar` components per orientation with automatic overflow detection via `ResizeObserver` + scroll metrics.
- **Draggable thumbs** — pointer-drag the thumb to scroll; track clicks jump the viewport; dragging continues when the cursor leaves the thumb.
- **Keyboard accessible viewport** — the viewport is focusable (`tabindex="0"`) with a visible focus ring; arrow keys scroll natively.
- **RTL scroll normalization** — detects the three browser RTL `scrollLeft` modes (`default` / `negative` / `reverse`) once per document (cached in a `WeakMap`) and normalizes them to a consistent 0 → max coordinate space for thumb math and drag behavior.
- **Full ARIA semantics** — scrollbars and thumbs are `aria-hidden` (custom scrollbars are purely decorative for AT); the root exposes `dir` from `useDirection`.
- **Composable structure** — `ScrollAreaRoot` / `ScrollAreaViewport` / `ScrollAreaScrollbar` / `ScrollAreaThumb` / `ScrollAreaCorner` are all exported from `@soybeanjs/headless/scroll-area` for custom styled builds, plus the `ScrollAreaCompact` aggregation.
- **Per-slot props forwarding** — `viewportProps`, `verticalScrollbarProps`, `horizontalScrollbarProps`, `thumbProps`, `cornerProps` on the compact component forward attributes to each region.
- **Corner rendering** — the corner is rendered only when both scrollbars are visible, sized by the crossing scrollbar thicknesses.
- **Size scaling** — `size` (xs…2xl) scales scrollbar thickness via `scrollAreaVariants`.
- **Performance** — all state uses `shallowRef`; derived values are cached in `computed`; RTL mode detection is cached per document; scroll listeners use `{ passive: true }`; drag listeners are cleaned up on `pointerup` / `pointercancel` / unmount.

## Usage

Usage examples for scroll-area are rendered on the site.

## Demos

Interactive demos for scroll-area are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): ScrollArea, ScrollAreaCompact, ScrollAreaCorner, ScrollAreaRoot, ScrollAreaScrollbar, ScrollAreaThumb, ScrollAreaViewport.

### ScrollArea

#### Props
Properties for the ScrollArea component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ScrollAreaUi>`; optional)
- `size`: Size of the ScrollArea component. (type `ThemeSize`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `ScrollAreaViewportProps`; optional)
- `verticalScrollbarProps`: Properties forwarded to the vertical scrollbar element. (type `ScrollAreaScrollbarProps`; optional)
- `horizontalScrollbarProps`: Properties forwarded to the horizontal scrollbar element. (type `ScrollAreaScrollbarProps`; optional)
- `thumbProps`: Properties forwarded to the thumb elements. (type `ScrollAreaThumbProps`; optional)
- `cornerProps`: Properties forwarded to the corner element. (type `ScrollAreaCornerProps`; optional)
- `type`: Controls scrollbar visibility behavior. (type `ScrollAreaType`; optional)
- `dir`: The reading direction of the scroll area. (type `Direction`; optional)
- `scrollHideDelay`: Delay before transient scrollbars are hidden. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ScrollAreaCompact

#### Props
Properties for the ScrollAreaCompact component.
- `viewportProps`: Properties forwarded to the viewport element. (type `ScrollAreaViewportProps`; optional)
- `verticalScrollbarProps`: Properties forwarded to the vertical scrollbar element. (type `ScrollAreaScrollbarProps`; optional)
- `horizontalScrollbarProps`: Properties forwarded to the horizontal scrollbar element. (type `ScrollAreaScrollbarProps`; optional)
- `thumbProps`: Properties forwarded to the thumb elements. (type `ScrollAreaThumbProps`; optional)
- `cornerProps`: Properties forwarded to the corner element. (type `ScrollAreaCornerProps`; optional)
- `type`: Controls scrollbar visibility behavior. (type `ScrollAreaType`; optional)
- `dir`: The reading direction of the scroll area. (type `Direction`; optional)
- `scrollHideDelay`: Delay before transient scrollbars are hidden. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the ScrollAreaCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)

### ScrollAreaCorner

#### Props
Properties for the ScrollAreaCorner component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ScrollAreaRoot

#### Props
Properties for the ScrollAreaRoot component.
- `type`: Controls scrollbar visibility behavior. (type `ScrollAreaType`; optional)
- `dir`: The reading direction of the scroll area. (type `Direction`; optional)
- `scrollHideDelay`: Delay before transient scrollbars are hidden. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ScrollAreaScrollbar

#### Props
Properties for the ScrollAreaScrollbar component.
- `orientation`: The scrollbar orientation. (type `ScrollAreaOrientation`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ScrollAreaThumb

#### Props
Properties for the ScrollAreaThumb component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ScrollAreaViewport

#### Props
Properties for the ScrollAreaViewport component.
- `nonce`: Adds a nonce to the injected style tag. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark comparison

| Concern                        | SoybeanUI                                                                                                 | Radix UI ScrollArea                          | Ant Design `ScrollBar`      |
| :----------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------------- | :-------------------------- |
| Headless / styled separation   | ✅ `@soybeanjs/headless/scroll-area` ships logic; `@soybeanjs/ui` ships `scv()` recipe                    | ❌ single package (headless-style core only) | ❌ single styled package    |
| Visibility modes               | `auto` / `always` / `hover` / `scroll` / `glimpse`                                                        | `auto` / `always` / `hover` / `scroll`       | `auto` / `always` / `hover` |
| Hide delay control             | `scrollHideDelay` prop (default 600ms)                                                                    | `scrollHideDelay` prop (default 600ms)       | —                           |
| RTL `scrollLeft` normalization | ✅ 3-mode detection (`default` / `negative` / `reverse`) + `WeakMap` cache                                | ✅ same approach                             | —                           |
| Thumb drag + track click       | ✅ pointer drag + track jump                                                                              | ✅ pointer drag + track jump                 | ✅                          |
| Keyboard focusable viewport    | ✅ `tabindex="0"` + focus ring                                                                            | ✅                                           | —                           |
| Corner auto-render             | ✅ rendered only when both scrollbars visible, sized by thickness                                         | ✅                                           | —                           |
| `dir` from ConfigProvider      | ✅ `useDirection` fallback                                                                                | ✅ `dir` prop                                | —                           |
| Region-level props forwarding  | ✅ `viewportProps` / `verticalScrollbarProps` / `horizontalScrollbarProps` / `thumbProps` / `cornerProps` | ✅ `asChild` on each part                    | —                           |
| SSR safety                     | ✅ no `window`/`document` in setup                                                                        | ✅                                           | —                           |

### Runtime considerations

1. **Thumb math is proportion-based** — `getThumbSize` maps `viewportSize / contentSize` onto the track size, clamped to a `MIN_THUMB_SIZE` of 18px. `getThumbOffset` clamps the scroll ratio to `[0, 1]` and inverts it for horizontal RTL.
2. **Metrics update triggers** — thumb size and offset are recalculated on viewport/content/scrollbar `ResizeObserver` callbacks and on every viewport `scroll` event (passive). `onScrollbarSizeChange` keeps the root's scrollbar size refs in sync for the corner sizing.
3. **Drag continues off-thumb** — `pointermove` / `pointerup` / `pointercancel` listeners are attached to `window` (not the thumb) so dragging works even when the cursor leaves the thumb. Listeners are removed on `pointerup` / `pointercancel` and on unmount.
4. **RTL mode detection is one-time** — `detectRtlScrollType` probes a temporary scroll container once per `Document` and caches the result in a `WeakMap`. The three modes (`default` / `negative` / `reverse`) are normalized so internal math always uses a 0 → max coordinate space.
5. **`type` affects visibility only, not behavior** — overflow detection, drag, and scroll events work identically for all modes; `type` only decides when the scrollbars are painted (`data-state="visible|hidden"`).
6. **SSR safety** — no `window` / `document` access in setup. The RTL probe and `ResizeObserver` only run client-side once elements exist.

## FAQ

### Which `type` should I use?

- `auto` — scrollbars appear only while the content overflows.
- `always` — scrollbars are always painted when there is overflow.
- `hover` — scrollbars fade in on pointer hover (desktop-friendly).
- `scroll` — scrollbars appear transiently while scrolling, then hide after `scrollHideDelay`.
- `glimpse` — a brief scrollbar glimpse on hover, useful for very clean minimal UIs.

### Why are the scrollbars `aria-hidden`?

The custom scrollbars are purely visual; the viewport remains a native scroll container, so assistive technologies can rely on native scrolling semantics and the focusable viewport. Marking the decorations `aria-hidden` prevents redundant announcements.

### How does RTL work?

Set `dir="rtl"` on the root (or rely on `ConfigProvider`). The component detects the browser's RTL `scrollLeft` mode once per document and normalizes thumb position, drag delta, and track clicks so they behave identically in LTR and RTL.

### Can I customize the scrollbar appearance?

Yes — pass `ui` (per-slot classes) to `SScrollArea`, or forward attributes via `verticalScrollbarProps` / `horizontalScrollbarProps` / `thumbProps`. For full control, build your own `ScrollAreaRoot` / `ScrollAreaViewport` / `ScrollAreaScrollbar` / `ScrollAreaThumb` composition from `@soybeanjs/headless/scroll-area`.

### How do I make the viewport keyboard focusable?

It already is — the viewport sets `tabindex="0"` by default (override via `viewportProps.tabindex`) and shows a focus ring via `focus-visible` styles.

### Why does the corner only appear sometimes?

The corner is rendered only when both horizontal and vertical scrollbars are visible simultaneously. Its size matches the crossing scrollbar thicknesses.

### Does it work with SSR?

Yes — setup never touches `window` / `document`. The RTL probe and `ResizeObserver` only activate client-side once the viewport mounts.

## Segment

- Page URL: /components/segment
- Markdown URL: /components/segment.md
- Description: A linear set of two or more mutually exclusive options presented as a unified control, with a sliding indicator that follows the active option. Use it for compact segmented pickers — time ranges, view toggles, or any small set of single-choice options — where the selection should change immediately. For a set of independent two-state buttons (single or multiple), use SToggleGroup; for plain tabbed content panels, use STabs.

# Segment

## Overview

A linear set of two or more mutually exclusive options presented as a unified control, with a sliding indicator that follows the active option. Use it for compact segmented pickers — time ranges, view toggles, or any small set of single-choice options — where the selection should change immediately. For a set of independent two-state buttons (single or multiple), use `SToggleGroup`; for plain tabbed content panels, use `STabs`.

## Usage

Usage examples for segment are rendered on the site.

## Features

- 🎯 Mutually exclusive single selection — one active segment at a time, backed by `useControllableState`
- 🎚 Controlled / uncontrolled — `v-model` and `defaultValue` (with type-safe generic values via `T extends SegmentOptionData`)
- 🧩 Data-driven composition — pass `items` and let headless `SegmentCompact` own iteration and indicator layout
- ✨ Optional sliding indicator — `enableIndicator` (default `true`), fully customizable through the `indicator` slot
- ⌨️ Roving focus keyboard navigation — arrow keys move between segments, `loop` wraps around, and arrow direction reverses in RTL
- 🎨 6 sizes × 2 orientations × 2 shapes (square/rounded) × 2 fills (auto/full) via `segmentVariants`
- 🧩 `ui` per-slot class overrides (`root` / `list` / `trigger` / `indicator` / `indicatorContent`), plus item-level `disabled`
- ♿ `role="tab"` + `aria-selected` with `data-state` reflection, axe-clean

## Component family

- `SSegment` — the styled wrapper that forwards props to the headless compact and injects `segmentVariants` classes
- `SegmentRoot` / `SegmentList` / `SegmentTrigger` / `SegmentIndicator` (headless) — domain primitives wrapping Tabs; DOM uses `data-soybean-segment-*`
- `SegmentCompact` (headless) — data-driven composition of those primitives; import from `@soybeanjs/headless/segment` for unstyled usage

## Demos

Interactive demos for segment are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (6): Segment, SegmentCompact, SegmentIndicator, SegmentList, SegmentRoot, SegmentTrigger.

### Segment

#### Props
Properties for the Segment component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SegmentUi>`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `shape`: Shape of the component. (type `SegmentShape`; optional)
- `fill`: Fill. (type `SegmentFill`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `enableIndicator`: Whether to enable indicator. (type `boolean`; optional)
- `listProps`: Properties forwarded to the list element. (type `SegmentListProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `SegmentTriggerProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `SegmentIndicatorProps`; optional)
- `modelValue`: The controlled value of the tab to activate. Can be bind as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs (type `T['value'] | null`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
#### Emits
Events for the Segment component.
- `update:modelValue`: Event handler called when the value changes (type `[payload: Exclude<T, undefined>]`; parameters `payload: Exclude<T, undefined>`)
#### Slots
Slots for the Segment component.
- `item`: Custom content for the item slot. (type `((props: T & { selected: boolean; }) => any) | undefined`)
- `indicator`: Custom content for the indicator slot. (type `(() => any) | undefined`)

### SegmentCompact

#### Props
Properties for the SegmentCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `enableIndicator`: Whether to enable indicator. (type `boolean`; optional)
- `listProps`: Properties forwarded to the list element. (type `SegmentListProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `SegmentTriggerProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `SegmentIndicatorProps`; optional)
- `modelValue`: The controlled value of the tab to activate. Can be bind as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs (type `T['value'] | null`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
#### Emits
Events for the SegmentCompact component.
- `update:modelValue`: Event handler called when the value changes (type `[payload: Exclude<T, undefined>]`; parameters `payload: Exclude<T, undefined>`)
#### Slots
Slots for the SegmentCompact component.
- `item`: Custom content for the item slot. (type `((props: T & { selected: boolean; }) => any) | undefined`)
- `indicator`: Custom content for the indicator slot. (type `(() => any) | undefined`)

### SegmentIndicator

#### Props
Properties for the SegmentIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SegmentList

- No documented props, emits, slots, or slot props were available.

### SegmentRoot

#### Props
Properties for the SegmentRoot component.
- `modelValue`: The controlled value of the tab to activate. Can be bind as `v-model`. (type `T`; optional)
- `defaultValue`: The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs (type `T`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
#### Emits
Events for the SegmentRoot component.
- `update:modelValue`: Event handler called when the value changes (type `[payload: Exclude<T, undefined>]`; parameters `payload: Exclude<T, undefined>`)

### SegmentTrigger

#### Props
Properties for the SegmentTrigger component.
- `value`: A unique value that associates the trigger with a content. (type `string | number`; required)
- `disabled`: When `true`, prevents the user from interacting with the tab. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`SegmentCompact` composes the headless `SegmentRoot`/`SegmentList`/`SegmentTrigger`/`SegmentIndicator` primitives (each wrapping the matching Tabs part): it iterates `items`, forwards `listProps`/`triggerProps`/`indicatorProps`, and exposes `item`/`indicator` slots. `SegmentTrigger` keeps the Tabs ARIA pattern (`role="tab"` + roving focus), so `loop` and `dir` (RTL) behave identically to tabs. `SSegment` is a thin wrapper that only computes `segmentVariants` (an alias of `tabsVariants`) and calls `provideSegmentUi`. The indicator is measured asynchronously (resize observer + post-flush watch), so it appears one frame after mount. `segment` maps to the segmented-control pattern; the benchmark libraries express it natively except shadcn, which typically uses Tabs.

| Capability                    | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :---------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Single (mutually exclusive)   |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Controlled / uncontrolled     |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Data-driven items             |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Sliding indicator             |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Roving focus arrow keys       |    ✅     |     ✅     |      ✅      |   ✅    |    —     |   —    |
| Loop navigation               |    ✅     |     —      |      —       |    —    |    —     |   —    |
| RTL-aware arrow direction     |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Orientation (vertical)        |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| Sizes × shapes × fills        |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| Item-level disabled           |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Custom item / indicator slots |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |

### Cautions

- `loop` and `unmountOnHide` default to `true`; `enableIndicator` defaults to `true`. Set `:enable-indicator="false"` to hide the sliding indicator (active state is then reflected through `data-state`).
- The indicator is positioned after an asynchronous layout measurement — it renders one frame after the active segment changes.
- Segments use the Tabs ARIA pattern (`role="tab"` + `aria-selected`), so avoid nesting segments inside another tabs-like control.
- `defaultValue` is only read on mount; subsequent changes are ignored (use `v-model` for external control).
- For icon-only items, add `aria-label` so the segment has an accessible name.
- `unmountOnHide` only matters when content panels are attached; a bare `SSegment` renders no content area.

## FAQ

### What is the difference between `SSegment` and `SToggleGroup`?

`SSegment` is a single mutually exclusive segmented control with a sliding indicator — exactly one option is active. `SToggleGroup` coordinates a set of independent toggle buttons that can be single or multiple selection, with no indicator.

### How do I disable the sliding indicator?

Pass `:enable-indicator="false"`. The selected segment is then highlighted through the `data-selected` style rules instead.

### How do I make arrow keys wrap around?

Keep `loop` (default `true`) — focus wraps from the last segment to the first and vice versa. Disabled segments are skipped automatically.

### How do I control the selected value externally?

Bind `v-model` for two-way control, or pass only `defaultValue` for uncontrolled usage. Use `items` to declare options; each item supports `value`, `label`, and `disabled`.

### Can I style the indicator and items?

Yes — the `indicator` slot replaces the default indicator content, the `item` slot receives `{ ...item, active }` for full customization, and `ui.root` / `ui.list` / `ui.trigger` / `ui.indicator` override classes per slot.

## Select

- Page URL: /components/select
- Markdown URL: /components/select.md
- Description: Displays a list of options for the user to pick from, triggered by a button. The trigger renders the selected value (or placeholder), and the popup supports keyboard navigation, typeahead, grouping, multiple selection, and clearable mode. Use it to pick one or more values from a bounded set; for free-text search over a list, use SCombobox; for cascading hierarchical data, use SCascader.

# Select

## Overview

Displays a list of options for the user to pick from, triggered by a button. The trigger renders the selected value (or placeholder), and the popup supports keyboard navigation, typeahead, grouping, multiple selection, and clearable mode. Use it to pick one or more values from a bounded set; for free-text search over a list, use `SCombobox`; for cascading hierarchical data, use `SCascader`.

## Usage

Usage examples for select are rendered on the site.

## Features

- 📊 Data-driven `SelectCompact` API — pass `items` (options use `label` / `value` fields)
- ⌨️ Full combobox interaction — pointer/keyboard open, Arrow/Home/End navigation, typeahead search, Enter/Space select, Escape close
- 🗂 Grouping with group labels, separators, and item indicators
- ✅ `multiple` selection with accumulation and deduplication
- 🧹 Clearable mode — trigger hover-reveal clear, plus `selectionBehavior` for whether re-selecting toggles or resets
- 📍 Item-aligned positioning (`position="item-aligned"`)
- 📋 Native form submission via a hidden proxy `<select>` (`SelectBubbleSelect`)
- 📌 `top` / `bottom` slots for fixed header and footer content inside the popup
- ♿ Full accessibility support — `role="combobox"` / `listbox` / `option`, axe-clean

## Demos

Interactive demos for select are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (20): Select, SelectArrow, SelectClear, SelectCompact, SelectContent, SelectGroup, SelectGroupLabel, SelectItem, SelectItemIndicator, SelectItemText, SelectPopup, SelectPortal, SelectRoot, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectTriggerIcon, SelectValue, SelectViewport.

### Select

#### Props
Properties for the Select component.
- `class`: the class of select trigger (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SelectUi>`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `items`: Items rendered by the component. (type `SelectOptionData<T>[]`; required)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `SelectTriggerProps`; optional)
- `triggerIconProps`: Properties forwarded to the trigger icon element. (type `SelectTriggerIconProps`; optional)
- `showTriggerIcon`: Whether to show the trigger icon. (type `boolean`; default `true`; optional)
- `clearLabel`: Clear label. (type `string`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `SelectClearProps`; optional)
- `placeholder`: Placeholder. (type `string`; optional)
- `valueProps`: Properties forwarded to the value element. (type `SelectValueProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `SelectPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `SelectContentProps`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `SelectPopupProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `SelectViewportProps`; optional)
- `scrollDownButtonProps`: Properties forwarded to the scroll down button element. (type `SelectScrollDownButtonProps`; optional)
- `scrollUpButtonProps`: Properties forwarded to the scroll up button element. (type `SelectScrollUpButtonProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `SelectGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `SelectGroupLabelProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `SelectItemProps`; optional)
- `itemTextProps`: Properties forwarded to the item text element. (type `SelectItemTextProps`; optional)
- `itemIndicatorProps`: Properties forwarded to the item indicator element. (type `SelectItemIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `SelectSeparatorProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `open`: The controlled open state of the Select. Can be bind as `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the select when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `nullableValue`: The value of the hidden native select option when the model value is nullish. (type `string`; optional)
- `dir`: The reading direction of the combobox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `autocomplete`: Native html input `autocomplete` attribute. (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with Select (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? T[] : T)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? T[] : T)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Select component.
- `update:modelValue`: No description. (type `[value: M extends true ? T[] : T]`; parameters `value: M extends true ? T[] : T`)
- `update:open`: Event handler called when the open state of the context menu changes. (type `[value: boolean]`; parameters `value: boolean`)
- `closeAutoFocus`: Emitted when close auto focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectItemEvent<T>]`; parameters `event: SelectItemEvent<T>`)
#### Slots
Slots for the Select component.
- `top`: Custom content rendered at the top of the popup, fixed above the scrollable list. (type `(() => any) | undefined`)
- `bottom`: Custom content rendered at the bottom of the popup, fixed below the scrollable list. (type `(() => any) | undefined`)
- `trigger-leading`: Custom content for the trigger leading slot. (type `(() => any) | undefined`)
- `trigger-value`: Custom content for the trigger value slot. (type `((props: SelectCompactTriggerValueSlotProps<T, M>) => any) | undefined`)
- `trigger-trailing`: Custom content for the trigger trailing slot. (type `(() => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `(() => any) | undefined`)
- `scroll-up-button`: Custom content for the scroll up button slot. (type `(() => any) | undefined`)
- `scroll-down-button`: Custom content for the scroll down button slot. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: SelectCompactGroupLabelSlotProps<T>) => any) | undefined`)
- `item-text`: Custom content for the item text slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)
- `item-indicator`: Custom content for the item indicator slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)

### SelectArrow

- No documented props, emits, slots, or slot props were available.

### SelectClear

#### Props
Properties for the SelectClear component.
- `ariaLabel`: Aria label for the clear button. (type `string`; optional)
- `disabled`: Whether the clear button is disabled. (type `boolean`; optional)

### SelectCompact

#### Props
Properties for the SelectCompact component.
- `items`: Items rendered by the component. (type `SelectOptionData<T>[]`; required)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `SelectTriggerProps`; optional)
- `triggerIconProps`: Properties forwarded to the trigger icon element. (type `SelectTriggerIconProps`; optional)
- `showTriggerIcon`: Whether to show the trigger icon. (type `boolean`; default `true`; optional)
- `clearLabel`: Clear label. (type `string`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `SelectClearProps`; optional)
- `placeholder`: Placeholder. (type `string`; optional)
- `valueProps`: Properties forwarded to the value element. (type `SelectValueProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `SelectPortalProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `SelectContentProps`; optional)
- `placement`: Placement. (type `import("@/index").Placement`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `SelectPopupProps`; optional)
- `viewportProps`: Properties forwarded to the viewport element. (type `SelectViewportProps`; optional)
- `scrollDownButtonProps`: Properties forwarded to the scroll down button element. (type `SelectScrollDownButtonProps`; optional)
- `scrollUpButtonProps`: Properties forwarded to the scroll up button element. (type `SelectScrollUpButtonProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `SelectGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `SelectGroupLabelProps`; optional)
- `itemProps`: Properties forwarded to the item element. (type `SelectItemProps`; optional)
- `itemTextProps`: Properties forwarded to the item text element. (type `SelectItemTextProps`; optional)
- `itemIndicatorProps`: Properties forwarded to the item indicator element. (type `SelectItemIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `SelectSeparatorProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `PopperArrowProps`; optional)
- `open`: The controlled open state of the Select. Can be bind as `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the select when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `nullableValue`: The value of the hidden native select option when the model value is nullish. (type `string`; optional)
- `dir`: The reading direction of the combobox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `autocomplete`: Native html input `autocomplete` attribute. (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with Select (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? T[] : T)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? T[] : T)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the SelectCompact component.
- `update:modelValue`: No description. (type `[value: M extends true ? T[] : T]`; parameters `value: M extends true ? T[] : T`)
- `update:open`: Event handler called when the open state of the context menu changes. (type `[value: boolean]`; parameters `value: boolean`)
- `closeAutoFocus`: Emitted when close auto focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectItemEvent<T>]`; parameters `event: SelectItemEvent<T>`)
#### Slots
Slots for the SelectCompact component.
- `top`: Custom content rendered at the top of the popup, fixed above the scrollable list. (type `(() => any) | undefined`)
- `bottom`: Custom content rendered at the bottom of the popup, fixed below the scrollable list. (type `(() => any) | undefined`)
- `trigger-leading`: Custom content for the trigger leading slot. (type `(() => any) | undefined`)
- `trigger-value`: Custom content for the trigger value slot. (type `((props: SelectCompactTriggerValueSlotProps<T, M>) => any) | undefined`)
- `trigger-trailing`: Custom content for the trigger trailing slot. (type `(() => any) | undefined`)
- `trigger-icon`: Custom content for the trigger icon slot. (type `(() => any) | undefined`)
- `scroll-up-button`: Custom content for the scroll up button slot. (type `(() => any) | undefined`)
- `scroll-down-button`: Custom content for the scroll down button slot. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: SelectCompactGroupLabelSlotProps<T>) => any) | undefined`)
- `item-text`: Custom content for the item text slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)
- `item-indicator`: Custom content for the item indicator slot. (type `((props: SelectCompactItemSlotProps<T>) => any) | undefined`)

### SelectContent

#### Props
Properties for the SelectContent component.
- `position`: The positioning mode to use `item-aligned (default)` - behaves similarly to a native MacOS menu by positioning content relative to the active item. <br> `popper` - positions content in the same way as our other primitives, for example `Popover` or `DropdownMenu`. (type `SelectPosition`; optional)
- `bodyLock`: The document.body will be lock, and scrolling will be disabled. (type `boolean`; default `true`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `SelectPopupProps`; optional)
- `open`: Whether the floating layer is open. Drives the positioning lifecycle (`isPositioned` resets when open flips); the positioning primitive itself has no open state, so consumers wire their own open state here. (type `boolean`; default `true`; optional)
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the anchor to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the anchor. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the anchor. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `false`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the anchor is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the anchor becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `disableOutsidePointerEvents`: When `true`, hover/focus/click interactions will be disabled on elements outside the `DismissableLayer`. Users will need to click twice on outside elements to interact with them: once to close the `DismissableLayer`, and again to trigger the element. (type `boolean`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the SelectContent component.
- `closeAutoFocus`: Emitted when close auto focus occurs. (type `[event: Event]`; parameters `event: Event`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)

### SelectGroup

- No documented props, emits, slots, or slot props were available.

### SelectGroupLabel

- No documented props, emits, slots, or slot props were available.

### SelectItem

#### Props
Properties for the SelectItem component.
- `value`: The value given as data when submitted with a `name`. (type `string | number`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `textValue`: Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the `SelectItemText` part. Use this when the content is complex, or you have non-textual content inside. (type `string`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SelectItem component.
- `select`: Event handler called when the selecting item. <br> It can be prevented by calling `event.preventDefault`. (type `[event: SelectItemEvent<T>]`; parameters `event: SelectItemEvent<T>`)

### SelectItemIndicator

#### Props
Properties for the SelectItemIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SelectItemText

- No documented props, emits, slots, or slot props were available.

### SelectPopup

- No documented props, emits, slots, or slot props were available.

### SelectPortal

- No documented props, emits, slots, or slot props were available.

### SelectRoot

#### Props
Properties for the SelectRoot component.
- `open`: The controlled open state of the Select. Can be bind as `v-model:open`. (type `boolean`; optional)
- `defaultOpen`: The open state of the select when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `nullableValue`: The value of the hidden native select option when the model value is nullish. (type `string`; optional)
- `dir`: The reading direction of the combobox when applicable. <br> If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode. (type `Direction`; optional)
- `autocomplete`: Native html input `autocomplete` attribute. (type `string`; optional)
- `disabled`: When `true`, prevents the user from interacting with Select (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? T[] : T)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? T[] : T)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the SelectRoot component.
- `update:modelValue`: No description. (type `[value: M extends true ? T[] : T]`; parameters `value: M extends true ? T[] : T`)
- `update:open`: Event handler called when the open state of the context menu changes. (type `[value: boolean]`; parameters `value: boolean`)

### SelectScrollDownButton

#### Props
Properties for the SelectScrollDownButton component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SelectScrollUpButton

#### Props
Properties for the SelectScrollUpButton component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SelectSeparator

- No documented props, emits, slots, or slot props were available.

### SelectTrigger

#### Props
Properties for the SelectTrigger component.
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `reference`: No description. (type `ReferenceElement`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SelectTriggerIcon

- No documented props, emits, slots, or slot props were available.

### SelectValue

#### Props
Properties for the SelectValue component.
- `placeholder`: The content that will be rendered inside the `SelectValue` when no `value` or `defaultValue` is set. (type `string`; optional)

### SelectViewport

#### Props
Properties for the SelectViewport component.
- `nonce`: Will add `nonce` attribute to the style tag which can be used by Content Security Policy. <br> If omitted, inherits globally from `ConfigProvider`. (type `string`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI builds select on a full ComboBox base: `SelectRoot` → `SelectTrigger` (`role="combobox"`) → `SelectValue` (collection label lookup) → `SelectContentImpl` (DismissableLayer + FocusScope + typeahead + keyboard nav) → `SelectItem`, with `SelectBubbleSelect` proxying native form submission. The `scv()` recipe `selectVariants` declares 16 slots and 7 size variants. This mirrors reka-ui / shadcn select semantics with a data-driven `SelectCompact` aggregation as the SoybeanUI differentiator.

| Capability                           | SoybeanUI | reka-ui `Select` | shadcn `Select` | Element Plus `el-select` |
| :----------------------------------- | :-------: | :--------------: | :-------------: | :----------------------: |
| headless/styled split                |    ✅     |        ✅        |        —        |            —             |
| combobox role + keyboard nav         |    ✅     |        ✅        |       ✅        |            ✅            |
| Typeahead search                     |    ✅     |        ✅        |        —        |            ✅            |
| Controlled / uncontrolled + multiple |    ✅     |        ✅        |        —        |            ✅            |
| Grouping + group labels              |    ✅     |        ✅        |       ✅        |            ✅            |
| Form proxying (BubbleSelect)         |    ✅     |        ✅        |        —        |            ✅            |
| Item-aligned positioning             |    ✅     |        ✅        |        —        |            —             |
| Data-driven Compact API              |    ✅     |        —         |        —        |            —             |
| Virtual scrolling                    |     —     |        —         |        —        |            ✅            |
| axe-clean (open state)               |    ✅     |        —         |       ✅        |            —             |

### Cautions

- Before the popup first opens, label lookup relies on the data-driven `fallbackLabel` computed from `items` — pass `items` (not just composition children) so the trigger text renders for `defaultValue` / controlled `modelValue`.
- `virtual` scrolling is not implemented; very large option lists may need custom virtualization.
- `multiple` with `clearable` uses `selectionBehavior` to decide whether clearing toggles off or resets the selection.

## FAQ

### How do I show the selected label before the popup is opened?

Pass `items` to `SSelect`. `SelectCompact` resolves the label from `items` via `fallbackLabel`, so `defaultValue` / controlled `modelValue` render on the trigger immediately.

### How do I enable multiple selection?

Pass `multiple`. Selections accumulate and deduplicate; `modelValue` becomes an array.

### How do I group options?

Pass grouped `items` — a group entry carries a `label` and a nested `items` array. Group headers render via the `group-label` slot, and separators via `separator`.

### How does the select submit in a native form?

The component renders a hidden native `<select>` (`SelectBubbleSelect`) mirroring the current value, so native form submission and browser autofill work.

### How do I make the trigger show an arrow or custom content?

Use the `trigger-icon` / `value` slots or the `showArrow`-equivalent slot surface; all 16 recipe slots are forwarded by `SSelect`.

### How do I clear the selected value from the trigger?

`clearable` defaults to `true`. With a value selected, hover or focus the trigger to reveal an ✕ button; clicking it resets `modelValue` to `undefined` (or `[]` when `multiple`). Pass `:clearable="false"` to hide it. Re-clicking the selected option still follows `selectionBehavior`.

### How do I add fixed header or footer content inside the popup?

Use the `top` and `bottom` slots. `top` renders above the scrollable list and `bottom` below it; both stay fixed while only the middle option list scrolls.

## Separator

- Page URL: /components/separator
- Markdown URL: /components/separator.md
- Description: The SSeparator component visually and semantically separates content sections. It renders a horizontal or vertical line, optionally with a label centered (or aligned) along it. Use it to divide related content blocks, group menu items, or structure form sections.

# Separator

## Overview

The `SSeparator` component visually and semantically separates content sections. It renders a horizontal or vertical line, optionally with a label centered (or aligned) along it. Use it to divide related content blocks, group menu items, or structure form sections.

For layout-level spacing between sections, prefer the [`SCard`](/components/card) or UnoCSS spacing utilities; use `SSeparator` when a visible dividing line aids comprehension.

## Usage

Usage examples for separator are rendered on the site.

## Features

- 📏 **Orientation** — Switch between `horizontal` and `vertical` layouts.
- 🏷️ **Label support** — Render text or custom content inside the separator via the `label` prop or default slot.
- ↔️ **Alignment** — Position the label at `start`, `center`, or `end`.
- 〰️ **Border styles** — Choose `solid`, `dashed`, or `dotted` line styles.
- 📐 **Size scaling** — Six sizes (`xs`–`2xl`) control label typography and spacing.
- ♿ **Accessibility** — `role="separator"` with `aria-orientation`; `decorative` prop removes the element from the accessibility tree for purely visual dividers.
- 🎨 **Per-slot overrides** — `ui` prop and `class` allow fine-grained styling of `root` and `label` slots.
- 🌐 **RTL aware** — Label positioning and translation automatically adjust for right-to-left layouts.

## Demos

Interactive demos for separator are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): Separator, SeparatorCompact, SeparatorLabel, SeparatorRoot.

### Separator

#### Props
Properties for the Separator component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SeparatorUi>`; optional)
- `align`: Align. (type `Align`; optional)
- `border`: Border. (type `SeparatorBorder`; optional)
- `label`: Label text rendered by the component. (type `string`; optional)
- `labelProps`: Properties forwarded to the label element. (type `SeparatorLabelProps`; optional)
- `orientation`: Orientation of the component. Either `vertical` or `horizontal`. Defaults to `horizontal`. (type `DataOrientation`; optional)
- `decorative`: Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. (type `boolean`; optional)

### SeparatorCompact

#### Props
Properties for the SeparatorCompact component.
- `label`: Label text rendered by the component. (type `string`; optional)
- `labelProps`: Properties forwarded to the label element. (type `SeparatorLabelProps`; optional)
- `orientation`: Orientation of the component. Either `vertical` or `horizontal`. Defaults to `horizontal`. (type `DataOrientation`; optional)
- `decorative`: Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. (type `boolean`; optional)
#### Slots
Slots for the SeparatorCompact component.
- `label`: Custom content for the label slot. (type `(() => any) | undefined`)

### SeparatorLabel

- No documented props, emits, slots, or slot props were available.

### SeparatorRoot

#### Props
Properties for the SeparatorRoot component.
- `orientation`: Orientation of the component. Either `vertical` or `horizontal`. Defaults to `horizontal`. (type `DataOrientation`; optional)
- `decorative`: Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. (type `boolean`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI splits `Separator` into a headless layer (`@soybeanjs/headless/separator`) that owns `SeparatorRoot` (role/aria/orientation), `SeparatorLabel`, and `SeparatorCompact` (composition + label visibility logic), and a styled layer (`@soybeanjs/ui`) that owns the `scv()` variant recipe (size/orientation/align/border) and class injection via `provideSeparatorUi`. This follows the shadcn/ui headless/styled separation.

| Aspect       | SoybeanUI                                                                     | Ant Design `Divider` | Element Plus `ElDivider` | MUI `Divider`    | Mantine `Divider` | shadcn/ui `Separator` |
| :----------- | :---------------------------------------------------------------------------- | :------------------- | :----------------------- | :--------------- | :---------------- | :-------------------- |
| Architecture | headless + styled split, `SeparatorUiSlot` (root/label) + Compact aggregation | single component     | single component         | single component | single component  | headless + styled     |
| Label        | `label` prop + default slot; `align` (start/center/end)                       | `orientation` prop   | `content-position`       | —                | `labelPosition`   | —                     |
| Border style | `border` (solid/dashed/dotted)                                                | `dashed` prop        | `border-style` prop      | —                | `variant`         | —                     |
| Size scaling | `size` (xs–2xl) controls label typography + spacing                           | —                    | —                        | —                | `size`            | —                     |
| Decorative   | `decorative` → `role="none"`                                                  | —                    | —                        | —                | —                 | `decorative`          |
| RTL          | `rtl:translate-x` + logical `start-*` positioning                             | —                    | —                        | —                | —                 | —                     |

### Runtime cautions

- **Vertical separators**: labels are intentionally hidden when `orientation="vertical"` because the label cannot be meaningfully positioned along a vertical line. If you need a label next to a vertical separator, place it outside the component.
- **Decorative mode**: when `decorative` is `true`, the element receives `role="none"` and `aria-orientation` is omitted so it is removed from the accessibility tree. Use this for purely visual dividers that screen readers should skip.
- **Full width / height**: horizontal separators default to `w-full` and vertical separators to `h-full`. Wrap vertical separators in a flex container with a fixed height for correct rendering.

### FAQ

**When should I use `decorative`?**
Set `decorative` when the separator is purely visual and does not represent a semantic content boundary. This sets `role="none"`, hiding it from screen readers. For content section dividers that convey meaning, leave `decorative` unset (defaults to `role="separator"`).

**Why is my label not showing on a vertical separator?**
Labels are intentionally suppressed for vertical orientations. Use a horizontal separator for labeled dividers, or place the label text outside the component.

**How do I customize the label element's attributes?**
Pass `labelProps` — it is forwarded directly to the `SeparatorLabel` element. For class overrides, use the `ui.label` slot instead.

**How do I make the separator full-width?**
Horizontal separators are `w-full` by default. For vertical separators, ensure the parent container has a defined height; the separator uses `h-full`.

## Sheet

- Page URL: /components/sheet
- Markdown URL: /components/sheet.md
- Description: A panel that slides out from the edge of the screen. It reuses the declarative API and slot contract of SDialog (same headless DialogCompact base, same modal/focus/dismissable behavior), and adds side to control where the panel enters — top/bottom/left/right (default right).

# Sheet

## Overview

A panel that slides out from the edge of the screen. It reuses the declarative API and slot contract of `SDialog` (same headless `DialogCompact` base, same modal/focus/dismissable behavior), and adds `side` to control where the panel enters — `top`/`bottom`/`left`/`right` (default `right`).

`SSheet` combines the headless dialog primitive family with the `sheetVariants` style recipe (extends `dialogVariants`, 6 sizes × 4 sides).

> Looking for a gesture-driven panel with snap points and swipe dismiss? That is [Drawer](/components/drawer) — the sheet is deliberately "a dialog with a side".

## Usage

Usage examples for sheet are rendered on the site.

## Features

- 🧩 Reuses the dialog base — built on `DialogCompact`, inherits `SDialog`'s slots, events, per-part `*Props`, `pure`, `isAlert` and the imperative `dialog(...)` API
- 🧭 4 sides — `side="top"`/`"bottom"`/`"left"`/`"right"` (default `right`); RTL-aware slide direction for left/right
- 🎭 Modal by default — `aria-modal`, `useHideOthers`, outside-pointer blocking and focus trapping, same as `SDialog`
- ❌ Closable — `showClose`, Escape, outside pointer/focus and the close button all dismiss
- 🎞️ Animated — enter/exit transitions (`slide-in-from-*` / `slide-out-to-*`) driven by the open state
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ⛶ Fullscreen — `showFullscreen` renders a toggle; `fullscreen`/`defaultFullscreen` drive a `v-model:fullscreen` state that grows the panel to the viewport
- 🔘 Cancel/confirm footer — `showCancel`/`showConfirm` with localized `cancelText`/`confirmText`
- ♿ Accessible — `role="dialog"`, focus trap + loop, focus restoration on close, `axe-core` zero violations

## Component family

- `SSheet` (styled) — the entry wrapper; `sheetVariants` recipe (`size` + `side`) with dynamic slot forwarding
- All other parts come from the headless dialog family (see `Dialog`): `DialogRoot`, `DialogTrigger`, `DialogOverlay`, `DialogPopup`, `DialogHeader`, `DialogContent`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose`, `DialogCancel`, `DialogConfirm`, `DialogCompact`

## Demos

Interactive demos for sheet are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Sheet.

### Sheet

#### Props
Properties for the Sheet component.
- `side`: Side placement of the component. (type `Side`; optional)
- `showFullscreen`: Whether show the fullscreen toggle button in the header of the dialog. (type `boolean`; default `false`; optional)
- `class`: the popup class of the dialog (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<DialogUi>`; optional)
- `title`: The title of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `title` slot is not provided. (type `string`; optional)
- `description`: The description of the dialog. This is used for accessibility purposes and will be rendered in the content of the dialog if the `description` slot is not provided. (type `string`; optional)
- `icon`: The icon of the dialog. This is used for accessibility purposes and will be rendered in the header of the dialog if the `icon` slot is not provided. (type `string | import("vue").Component | VNode<import("vue").RendererNode, import("vue").RendererElement, { [key: string]: ...`; optional)
- `showClose`: Whether show the close button in the header of the dialog. (type `boolean`; default `true`; optional)
- `pure`: Whether to use the pure version of the dialog, which does not include the header and footer. This is useful when you want to fully control the content of the dialog and do not need the built-in header and footer. (type `boolean`; default `false`; optional)
- `showCancel`: Whether to show the cancel button. When set to `onlyWarning`, the cancel button will only be shown when the dialog is an alert dialog with `alertType="warning"`. When set to `true`, the cancel button will always be shown. (type `boolean | 'onlyWarning'`; default `'onlyWarning'`; optional)
- `cancelText`: The text of the cancel button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `cancel` slot is not provided. Defaults to the localized `dialog.cancel` message from `ConfigProvider`. (type `string`; optional)
- `showConfirm`: Whether to show the confirm button when the dialog is an alert dialog. The default value is `true` when the dialog is an alert dialog. (type `boolean`; optional)
- `confirmText`: The text of the confirm button. This is used for accessibility purposes and will be rendered in the footer of the dialog if the `confirm` slot is not provided. Defaults to the localized `dialog.confirm` message from `ConfigProvider`. (type `string`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `DialogTriggerProps`; optional)
- `overlayProps`: Properties forwarded to the overlay element. (type `DialogOverlayProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `DialogPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `DialogPopupProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `DialogHeaderProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `DialogContentProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `DialogFooterProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `DialogTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `DialogDescriptionProps`; optional)
- `closeProps`: Properties forwarded to the close element. (type `DialogCloseProps`; optional)
- `fullscreenProps`: Properties forwarded to the fullscreen element. (type `DialogFullscreenProps`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `DialogCancelProps`; optional)
- `confirmProps`: Properties forwarded to the confirm element. (type `DialogConfirmProps`; optional)
- `modal`: The modality of the dialog. When set to `true`, interaction with outside elements will be disabled and only dialog content will be visible to screen readers. Set to `'trap-focus'` to trap focus while still letting outside pointer events through (non-modal side panels such as `Drawer` in the `'trap-focus'` tier). (type `ModalityTier`; default `true`; optional)
- `dir`: The text direction of the dialog (type `Direction`; optional)
- `isAlert`: Whether the dialog is an alert dialog. An alert dialog is a dialog that interrupts the user's workflow to communicate an important message and requires a response. When set to `true`, the dialog will have `role="alertdialog"` and will require a `DialogTitle` to be provided. This is used for accessibility purposes. (type `boolean`; default `false`; optional)
- `alertType`: The alert type of the dialog, which determines the default icon and styles when the dialog is an alert dialog. (type `DialogAlertType`; optional)
- `draggable`: Whether the dialog can be moved by dragging its header. (type `boolean`; default `false`; optional)
- `fullscreen`: The controlled fullscreen state of the dialog. Can be bound with `v-model:fullscreen`. (type `boolean`; default `undefined`; optional)
- `defaultFullscreen`: The fullscreen state of the dialog when it is initially rendered. Use when you do not need to control its fullscreen state. (type `boolean`; default `false`; optional)
- `open`: The controlled open state of the dialog. Can be bound with `v-model:open`. (type `boolean`; default `undefined`; optional)
- `defaultOpen`: The open state of the dialog when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; default `false`; optional)
#### Emits
Events for the Sheet component.
- `update:open`: Event handler called when the open state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `update:fullscreen`: Event handler called when the fullscreen state of the dialog changes. (type `[value: boolean]`; parameters `value: boolean`)
- `click`: Event handler called when the dialog trigger is activated. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `close`: Event handler called when the dialog is requested to be closed. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `fullscreen`: Event handler called when the fullscreen state of the dialog is requested to be toggled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `confirm`: Event handler called when the dialog is requested to be closed by confirming. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
- `cancel`: Event handler called when the dialog is requested to be canceled. (type `[event: MouseEvent]`; parameters `event: MouseEvent`)
#### Slots
Slots for the Sheet component.
- `default`: Custom content for the default slot. (type `(props: DialogCompactBaseSlotProps) => any`; parameters `props: DialogCompactBaseSlotProps`)
- `trigger`: Custom content for the trigger slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `close`: Custom content for the close slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `fullscreen`: Custom content for the fullscreen slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `cancel`: Custom content for the cancel slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)
- `confirm`: Custom content for the confirm slot. (type `((props: DialogCompactBaseSlotProps) => any) | undefined`)

## Notes

### Architecture and benchmark differences

`SSheet` is a thin styled wrapper: it forwards every prop/slot/event to the headless `DialogCompact` and only supplies the `sheetVariants` recipe that extends `dialogVariants` with side-specific `popup` classes. This keeps sheet and dialog behavior identical while varying only presentation — the same headless/styled split as shadcn-ui/vaul-style panels, versus Ant Design's `drawer` (single styled component with `placement`/`width`/`closable`/`mask` props) and Element Plus/Mantine/Naive UI equivalents.

| Capability                | SoybeanUI | shadcn/ui | Ant Design Drawer | Element Plus Drawer | Mantine Drawer | Naive UI Drawer |
| :------------------------ | :-------: | :-------: | :---------------: | :-----------------: | :------------: | :-------------: |
| Reuses dialog base        |    ✅     |    ✅     |         —         |          —          |       —        |        —        |
| Headless/styled split     |    ✅     |    ✅     |         —         |          —          |       —        |        —        |
| 4 placements (side)       |    ✅     |    ✅     |        ✅         |         ✅          |       ✅       |       ✅        |
| Modal (aria-modal + trap) |    ✅     |    ✅     |        ✅         |         ✅          |       ✅       |       ✅        |
| Focus return on close     |    ✅     |    ✅     |        ✅         |         ✅          |       ✅       |       ✅        |
| Sizes (6)                 |    ✅     |     —     |         —         |          —          |       —        |        —        |
| Pure (no header/footer)   |    ✅     |     —     |         —         |          —          |       —        |        —        |

`—` = unsupported or a different interaction model.

### Cautions

- Sheet inherits the dialog contract: it is modal by default and the popup teleports to `document.body`; Escape/outside interaction dismisses it.
- `side` only changes the slide direction and position classes; the accessible `role` remains `dialog` (a sheet is not a distinct ARIA role).
- Left/right sheets slide in the logical direction and are mirrored under RTL (`dir`).
- In fullscreen the panel covers the viewport from the edge it is anchored to, so `side` only decides which edge that is; the per-side size caps (`w-3/4`/`sm:max-w-sm`, and the `100dvh - 2rem` height cap) are released.
- The imperative `dialog(...)` API also renders sheets if you pass the matching options — no separate sheet service is needed.

### Migrating from `SDrawer` (v0.50.0)

The name `SDrawer` now belongs to the gesture-driven [Drawer](/components/drawer). The side panel keeps its exact behaviour under a new name:

| Before                                        | After                                      |
| :-------------------------------------------- | :----------------------------------------- |
| `SDrawer` (side panel)                        | `SSheet`                                   |
| `@soybeanjs/ui` → `SDrawer`                   | `@soybeanjs/ui` → `SSheet`                 |
| `drawerVariants`                              | `sheetVariants`                            |
| `DrawerProps` / `DrawerEmits` / `DrawerSlots` | `SheetProps` / `SheetEmits` / `SheetSlots` |

```vue

<SDrawer v-model:open="open" side="left" title="Filters">...</SDrawer>

<SSheet v-model:open="open" side="left" title="Filters">...</SSheet>
```

## FAQ

### How do I slide the sheet from a specific edge?

Set `side` to `top`/`bottom`/`left`/`right`:

```vue
<SSheet v-model:open="open" side="left" title="Filters">...</SSheet>
```

### How do I control the open state?

Bind `open` with `v-model`, or use `defaultOpen` for an uncontrolled sheet:

```vue
<SSheet v-model:open="open" title="Settings">...</SSheet>
```

### How do I add cancel/confirm actions?

Use the `footer` slot, or rely on `showCancel`/`showConfirm` with localized text:

```vue

  <template #trigger><SButton>Open</SButton></template>

```

### How do I build a custom sheet?

Use `pure` and fill the default slot:

```vue

  <div class="custom">...</div>

```

### How do I make the sheet fullscreen?

Render the header toggle with `show-fullscreen`, or drive the state with `v-model:fullscreen`. Either way the panel grows to the viewport from its `side` edge:

```vue

  <template #trigger><SButton>Open</SButton></template>

```

## Skeleton

- Page URL: /components/skeleton
- Markdown URL: /components/skeleton.md
- Description: A placeholder used to indicate that content is still loading. SSkeleton combines the headless Skeleton primitive (zero styles) with the skeletonVariants style recipe (6 sizes × 2 shapes × animated toggle) and is decorative (aria-hidden by default).

# Skeleton

## Overview

A placeholder used to indicate that content is still loading. `SSkeleton` combines the headless `Skeleton` primitive (zero styles) with the `skeletonVariants` style recipe (6 sizes × 2 shapes × animated toggle) and is decorative (`aria-hidden` by default).

Use it to reserve space and reduce layout shift while data loads — cards, tables, lists, and detail blocks. Prefer `spinner` for an indefinite "please wait" on an action, and `empty` for the final no-data state.

## Usage

Usage examples for skeleton are rendered on the site.

## Features

- 🧩 Headless/styled split — the headless `Skeleton` primitive owns `aria-hidden`/`as`/`asChild`; `SSkeleton` injects `skeletonVariants`
- 📐 6 size presets — xs–2xl that set both height and width
- 🟦 2 shapes — `auto` (rounded) and `rounded` (pill/circle)
- ⚡ Animated — `animate-pulse` by default; set `animated=false` for a static block
- ♿ Decorative by default — `aria-hidden="true"` unless overridden, so it never confuses assistive tech
- 🔧 Polymorphic — `as`/`asChild` to render as any element
- 🎛️ Custom sizing — override dimensions via `class` for bespoke placeholders

## Component family

- `SSkeleton` (styled) — the entry wrapper; `skeletonVariants` recipe
- `Skeleton` (headless) — the state-free primitive; `aria-hidden` default + `as`/`asChild`

## Demos

Interactive demos for skeleton are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Skeleton.

### Skeleton

#### Props
Properties for the Skeleton component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `animated`: Whether the skeleton should have an animation effect. Defaults to `true`. (type `boolean`; optional)
- `shape`: Shape of the component. (type `SkeletonShape`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

The headless `Skeleton` is a state-free primitive that only owns the decorative `aria-hidden` default and polymorphism, while `SSkeleton` keeps all styling in `skeletonVariants`. This mirrors shadcn/ui's headless/styled split, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled skeleton with `paragraph`/`avatar`/`title` composition props. SoybeanUI stays minimal (one primitive) and expects consumers to compose placeholders with grid/flex — the `size` scale and `rounded` pill shape cover the common cases the single-package libraries expose as presets.

| Capability               | SoybeanUI | shadcn/ui | Ant Design Skeleton | Element Plus Skeleton | Mantine Skeleton | Naive UI Skeleton |
| :----------------------- | :-------: | :-------: | :-----------------: | :-------------------: | :--------------: | :---------------: |
| Headless/styled split    |    ✅     |    ✅     |          —          |           —           |        —         |         —         |
| Animated pulse           |    ✅     |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |
| Size variants (6)        |    ✅     |     —     |          —          |          ✅           |        ✅        |         —         |
| Shape (rounded / pill)   |    ✅     |     —     |          —          |           —           |        —         |         —         |
| `aria-hidden` by default |    ✅     |     —     |          —          |           —           |        —         |         —         |
| `as`/`asChild`           |    ✅     |    ✅     |          —          |           —           |        —         |         —         |

`—` = unsupported or a different interaction model.

### Cautions

- `SSkeleton` is decorative and `aria-hidden` by default. If the placeholder carries meaning, put a visually-hidden label (or real content once loaded) in an accessible container.
- `animated` defaults to `true` (an `animate-pulse`). Set `animated="false"` for a static block to avoid motion.
- The `size` presets set both width and height; use `class` (e.g. `w-full h-32`) to customize dimensions.
- Compose multiple `SSkeleton` blocks with your own layout (flex/grid) for card/table-shaped placeholders.
- Rendered as a `<div>` by default; use `as`/`asChild` when a different element is required.

### Roadmap

No blocking gaps identified for the core skeleton API. Composed `skeleton` blocks (title/avatar/paragraph) are left to consumer composition rather than shipped as presets.

## FAQ

### How do I render a circular skeleton?

Use `shape="rounded"`:

```vue

```

### How do I disable the animation?

Set `animated="false"`:

```vue

```

### How do I set a custom size?

Override with `class` (the presets only set defaults):

```vue

```

### Is it accessible?

Yes — `SSkeleton` is `aria-hidden` by default so screen readers ignore it. If the loading state is meaningful, wrap it with an `aria-live`/`aria-label` container and replace it with real content when ready.

### How do I build a card-shaped placeholder?

Compose several blocks with your own layout:

```vue
<div class="space-y-3 rounded-md border p-4">
  <SSkeleton class="h-6 w-1/3" />
  <SSkeleton class="h-4 w-full" />
  <SSkeleton class="h-4 w-2/3" />
</div>
```

## Slider

- Page URL: /components/slider
- Markdown URL: /components/slider.md
- Description: A slider for picking one or more numeric values within a continuous range, supporting horizontal and vertical orientations, multi-thumb range mode, RTL and inverted directions, and complete keyboard navigation. Use it when the value belongs to a bounded numeric range and the user should adjust it with mouse or keyboard precision; when the value is free-form text or numbers, prefer SInputNumber instead.

# Slider

## Overview

A slider for picking one or more numeric values within a continuous range, supporting horizontal and vertical orientations, multi-thumb range mode, RTL and inverted directions, and complete keyboard navigation. Use it when the value belongs to a bounded numeric range and the user should adjust it with mouse or keyboard precision; when the value is free-form text or numbers, prefer `SInputNumber` instead.

## Usage

Usage examples for slider are rendered on the site.

## Features

- 🎚 `modelValue` / `defaultValue` — controlled and uncontrolled modes backed by `useControllableState`
- 🔢 Single or multi-thumb range — pass an array with two values for a range slider
- ⌨️ Full keyboard support — Arrow keys step by `step`, PageUp/PageDown and Shift+Arrow jump 10 steps, Home/End go to min/max
- ↔ RTL-aware direction with `dir`, plus `inverted` to flip the value direction
- 📐 Horizontal and vertical orientations with `aria-orientation` reflection
- 📋 Native form proxy — a visually hidden input (or `name[0]`/`name[1]` pair for ranges) carries the value with `name` / `required`
- 🎨 6 sizes and 8 colors via `sliderVariants`
- 🧩 `trackProps` / `rangeProps` / `thumbProps` forwarding plus a default slot to customize thumb content
- 📏 `minStepsBetweenThumbs` and `thumbAlignment` (`contain` / `overflow`) for precise range control

## Demos

Interactive demos for slider are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (6): Slider, SliderCompact, SliderRange, SliderRoot, SliderThumb, SliderTrack.

### Slider

#### Props
Properties for the Slider component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SliderUi>`; optional)
- `trackProps`: Properties forwarded to the track element. (type `SliderTrackProps`; optional)
- `rangeProps`: Properties forwarded to the range element. (type `SliderRangeProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `BaseProps`; optional)
- `modelValue`: The controlled value of the slider. Can be bind as `v-model`. (type `number[]`; optional)
- `defaultValue`: The initial value of the slider when uncontrolled. (type `number[]`; optional)
- `disabled`: Whether the slider is disabled. (type `boolean`; optional)
- `orientation`: The orientation of the slider. (type `DataOrientation`; optional)
- `dir`: The reading direction of the slider. (type `Direction`; optional)
- `inverted`: Whether the slider value direction is inverted. (type `boolean`; optional)
- `min`: The minimum value. (type `number`; optional)
- `max`: The maximum value. (type `number`; optional)
- `step`: The stepping interval. (type `number`; optional)
- `minStepsBetweenThumbs`: The minimum permitted steps between multiple thumbs. (type `number`; optional)
- `thumbAlignment`: Whether thumbs stay within the track bounds or may overflow it. (type `SliderThumbAlignment`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Slider component.
- `update:modelValue`: Event handler called when the slider value changes. (type `[value: number[]]`; parameters `value: number[]`)
- `valueCommit`: Event handler called when a slider interaction is committed. (type `[value: number[]]`; parameters `value: number[]`)

### SliderCompact

#### Props
Properties for the SliderCompact component.
- `trackProps`: Properties forwarded to the track element. (type `SliderTrackProps`; optional)
- `rangeProps`: Properties forwarded to the range element. (type `SliderRangeProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `BaseProps`; optional)
- `modelValue`: The controlled value of the slider. Can be bind as `v-model`. (type `number[]`; optional)
- `defaultValue`: The initial value of the slider when uncontrolled. (type `number[]`; optional)
- `disabled`: Whether the slider is disabled. (type `boolean`; optional)
- `orientation`: The orientation of the slider. (type `DataOrientation`; optional)
- `dir`: The reading direction of the slider. (type `Direction`; optional)
- `inverted`: Whether the slider value direction is inverted. (type `boolean`; optional)
- `min`: The minimum value. (type `number`; optional)
- `max`: The maximum value. (type `number`; optional)
- `step`: The stepping interval. (type `number`; optional)
- `minStepsBetweenThumbs`: The minimum permitted steps between multiple thumbs. (type `number`; optional)
- `thumbAlignment`: Whether thumbs stay within the track bounds or may overflow it. (type `SliderThumbAlignment`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SliderCompact component.
- `update:modelValue`: Event handler called when the slider value changes. (type `[value: number[]]`; parameters `value: number[]`)
- `valueCommit`: Event handler called when a slider interaction is committed. (type `[value: number[]]`; parameters `value: number[]`)
#### Slots
Slots for the SliderCompact component.
- `default`: Custom content for the default slot. (type `((props: SliderCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the SliderCompact component.
- `modelValue`: Current model value. (type `number[]`; required)
- `index`: Current thumb index. (type `number`; required)
- `value`: Current thumb value. (type `number`; required)

### SliderRange

#### Props
Properties for the SliderRange component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SliderRoot

#### Props
Properties for the SliderRoot component.
- `modelValue`: The controlled value of the slider. Can be bind as `v-model`. (type `number[]`; optional)
- `defaultValue`: The initial value of the slider when uncontrolled. (type `number[]`; optional)
- `disabled`: Whether the slider is disabled. (type `boolean`; optional)
- `orientation`: The orientation of the slider. (type `DataOrientation`; optional)
- `dir`: The reading direction of the slider. (type `Direction`; optional)
- `inverted`: Whether the slider value direction is inverted. (type `boolean`; optional)
- `min`: The minimum value. (type `number`; optional)
- `max`: The maximum value. (type `number`; optional)
- `step`: The stepping interval. (type `number`; optional)
- `minStepsBetweenThumbs`: The minimum permitted steps between multiple thumbs. (type `number`; optional)
- `thumbAlignment`: Whether thumbs stay within the track bounds or may overflow it. (type `SliderThumbAlignment`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SliderRoot component.
- `update:modelValue`: Event handler called when the slider value changes. (type `[value: number[]]`; parameters `value: number[]`)
- `valueCommit`: Event handler called when a slider interaction is committed. (type `[value: number[]]`; parameters `value: number[]`)

### SliderThumb

#### Props
Properties for the SliderThumb component.
- `index`: The thumb index in the current slider value array. (type `number`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SliderTrack

#### Props
Properties for the SliderTrack component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI builds the slider from headless `SliderRoot` (`useControllableState` + value normalization + `VisuallyHiddenInput` form proxy) → `SliderTrack` (pointer drag, pointer-move/up/cancel on the document) → `SliderRange` (percentage span between thumbs) → `SliderThumb` (`role="slider"` + `aria-valuemin/max/now` + `aria-orientation`, focus-derived step navigation). `SliderCompact` composes root + track + range + thumbs and owns thumb iteration; the UI wrapper `SSlider` only computes variant classes via `sliderVariants` and injects the `ui` map through `provideSliderUi`.

| Capability                          | SoybeanUI | Ant Design `Slider` | Element Plus `Slider` | Mantine `Slider` | Naive UI `Slider` | shadcn `Slider` |
| :---------------------------------- | :-------: | :-----------------: | :-------------------: | :--------------: | :---------------: | :-------------: |
| headless/styled split               |    ✅     |          —          |           —           |        —         |         —         |       ✅        |
| Controlled/uncontrolled             |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Range (multi-thumb)                 |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Vertical orientation                |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Inverted / RTL                      |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Keyboard nav (Arrows/Home/End/Page) |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| `minStepsBetweenThumbs`             |    ✅     |          —          |           —           |        —         |         —         |       ✅        |
| Form proxy / `name` submit          |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Axe-clean                           |    ✅     |          —          |           —           |        —         |         —         |        —        |
| Marks (scale ticks)                 |    ➕     |         ✅          |          ✅           |        ✅        |        ✅         |        —        |
| Value tooltip while dragging        |    ➕     |         ✅          |          ✅           |        ✅        |        ✅         |        —        |
| Linked number input                 |    ➕     |         ✅          |           —           |        —         |         —         |        —        |

### Cautions

- A single thumb has no default accessible name — pass `aria-label` through `thumbProps` (range mode falls back to localized "Minimum"/"Maximum" labels automatically).
- Thumbs default to `contain` inside the track; `thumbAlignment="overflow"` lets them extend beyond the track bounds.
- The form proxy renders only when `name` is present on a `form`-classed root; pair it with a native `<form>` or the `SForm` integration.
- PageUp/PageDown and Shift+Arrow keys step 10× the `step` value; `minStepsBetweenThumbs` blocks thumbs from crossing each other.

## FAQ

### How do I create a range slider?

Pass an array with two values to `modelValue` (or `defaultValue`), e.g. `[20, 80]`. Two thumbs are rendered and `valueCommit` emits both values. Each thumb is labeled "Minimum"/"Maximum" (localized) unless you override `thumbProps['aria-label']`.

### How do I keep the two thumbs apart?

Set `minStepsBetweenThumbs` to the minimum number of steps between thumbs — stepping or dragging is rejected when the gap would fall below that threshold.

### How do I show the current value above the thumb?

Use the default slot, which receives `{ index, value, modelValue }` for each thumb, to render custom content. A built-in tooltip is a planned enhancement.

### What keyboard shortcuts are supported?

Arrow keys step by `step`, PageUp/PageDown and Shift+Arrow jump 10 steps, and Home/End jump to min/max. Direction keys follow `dir` and `inverted` (RTL flips horizontal arrows; `inverted` flips the value direction).

## Spinner

- Page URL: /components/spinner
- Markdown URL: /components/spinner.md
- Description: SSpinner is a lightweight loading indicator built on top of SIcon. It defaults to the Iconify svg-spinners collection and is suitable for inline loading states such as button loading, content placeholders, and async fetch indicators. Use the color and size props to match the surrounding UI, or swap the icon prop for any svg-spinners:* animation.

# Spinner

## Overview

`SSpinner` is a lightweight loading indicator built on top of `SIcon`. It defaults to the Iconify `svg-spinners` collection and is suitable for inline loading states such as button loading, content placeholders, and async fetch indicators. Use the `color` and `size` props to match the surrounding UI, or swap the `icon` prop for any `svg-spinners:*` animation.

## Usage

Usage examples for spinner are rendered on the site.

## Features

- 🎬 **Iconify svg-spinners** — Defaults to `svg-spinners:270-ring`; swap with any icon from the `svg-spinners` collection via the `icon` prop.
- 🎨 **Theme colors** — Eight color options (`current`, `primary`, `destructive`, `success`, `warning`, `info`, `carbon`, `secondary`, `accent`) using semantic tokens.
- 📐 **Size scaling** — Six sizes (`xs`–`2xl`) control the spinner dimensions.
- 🔧 **Icon passthrough** — All `SIcon` props (except `icon` and `color`) are forwarded, so `width`, `height`, `ssr`, and ARIA attributes pass through naturally.
- ♿ **Accessible by opt-in** — Pass `aria-label="Loading"` to announce the spinner to screen readers; defaults to `aria-hidden` for inline use inside text-bearing elements.
- 🌐 **Dark mode** — Uses semantic color tokens that adapt to dark themes automatically.

## Demos

Interactive demos for spinner are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Spinner.

### Spinner

#### Props
Properties for the Spinner component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `icon`: The spinner icon name from the Iconify svg-spinners collection. (type ``svg-spinners:${string}``; default `'svg-spinners:270-ring'`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ariaHidden`: Whether the icon is hidden from assistive technology. Defaults to `true` for decorative icons. Set to `false` or provide `ariaLabel` / `ariaLabelledby` to expose the icon. (type `boolean`; optional)
- `ariaLabel`: Accessible label for the icon. When provided, `aria-hidden` is not set so the label is announced. (type `string`; optional)
- `ariaLabelledby`: ID of an element that labels the icon. When provided, `aria-hidden` is not set so the label is announced. (type `string`; optional)

## Notes

### Architecture and benchmark differences

`SSpinner` is a UI-only component — it has no headless layer because it is a thin preset over `SIcon` (which already has a headless layer). It applies the `spinnerVariants` `cv()` recipe (color/size) and forwards all other `IconProps` to `SIcon`. This matches the shadcn/ui `Spinner` approach of wrapping an icon with preset styling.

| Aspect         | SoybeanUI                                     | shadcn/ui `Spinner` | MUI `CircularProgress` | Mantine `Loader`   | Ant Design `Spin`  |
| :------------- | :-------------------------------------------- | :------------------ | :--------------------- | :----------------- | :----------------- |
| Architecture   | UI-only preset over `SIcon`                   | styled SVG          | styled SVG             | styled SVG         | component + tip    |
| Icon source    | Iconify `svg-spinners` (swappable)            | inline SVG (fixed)  | inline SVG (fixed)     | inline SVG (fixed) | inline SVG (fixed) |
| Color variants | 8 semantic tokens                             | —                   | `color` prop           | `color` prop       | —                  |
| Size scaling   | `xs`–`2xl` (6 steps)                          | `sm`–`lg`           | `size` prop            | `xs`–`xl`          | `small`/`default`  |
| Custom icon    | `icon` prop accepts any `svg-spinners:*`      | —                   | —                      | —                  | `indicator` slot   |
| A11y           | `aria-hidden` by default; `aria-label` opt-in | `role="status"`     | `aria-label`           | —                  | `tip` text         |

### Runtime cautions

- **Accessibility**: The spinner inherits `aria-hidden="true"` from `SIcon` by default. This is intentional for the most common use case — a spinner inside a button that already has text (e.g., "Loading..."). For standalone loading indicators, pass `aria-label="Loading"` so screen readers announce the loading state.
- **Icon swappability**: The `icon` prop is typed as `` `svg-spinners:${string}` `` to ensure only valid Iconify spinner icons are used. To use a non-spinner icon, use `SIcon` directly.
- **Color vs `text-*`**: The `color` prop applies semantic theme color classes (e.g., `text-primary`). For custom colors, pass a `class` override (e.g., `class="text-orange-500"`); the `class` prop merges with variant classes via `cv()`.

### FAQ

**How do I make the spinner accessible to screen readers?**
Pass an `aria-label`: `<SSpinner aria-label="Loading data" />`. Without it, the spinner is `aria-hidden` and invisible to assistive technology. This is correct when the spinner sits inside a button or next to text that already describes the loading state.

**Can I use a different spinner animation?**
Yes. Pass any icon from the Iconify `svg-spinners` collection: `<SSpinner icon="svg-spinners:ring-resize" />`. Browse available icons at [icones.js.org](https://icones.js.org/collection/svg-spinners).

**How do I control the spinner size beyond the `size` prop?**
The `size` prop maps to fixed dimensions (`size-3` to `size-10`). For custom sizing, pass `width` and `height` props (forwarded to `SIcon`) or override with `class="w-8 h-8"`.

**Why is there no headless layer for Spinner?**
The spinner is a purely presentational icon preset — it has no state, interactivity, or ARIA logic beyond what `SIcon` already provides. Adding a headless layer would be unnecessary indirection. The headless/styled split lives in `SIcon` itself.

## SplitNav

- Page URL: /components/split-nav
- Markdown URL: /components/split-nav.md
- Description: A split navigation for admin layouts. SSplitNav takes one menu tree and renders it across independent first-level and nested panes, instead of nesting every level in a single sidebar. It ships four layout modes — dual-vertical, vertical-horizontal, horizontal-vertical, and horizontal-dual-vertical. The first-level rail is a dedicated RovingFocus menu (Menubar-like arrow keys; Enter/Space to activate; ArrowDown on a horizontal parent, ArrowLeft/ArrowRight on a vertical parent to open the nested pane). Nested vertical panes reuse TreeMenuCompact; the nested horizontal pane reuses TreeNavCompact.

# SplitNav

## Overview

A split navigation for admin layouts. `SSplitNav` takes one menu tree and renders it across independent first-level and nested panes, instead of nesting every level in a single sidebar. It ships four layout modes — `dual-vertical`, `vertical-horizontal`, `horizontal-vertical`, and `horizontal-dual-vertical`. The first-level rail is a dedicated RovingFocus menu (Menubar-like arrow keys; Enter/Space to activate; ArrowDown on a horizontal parent, ArrowLeft/ArrowRight on a vertical parent to open the nested pane). Nested vertical panes reuse `TreeMenuCompact`; the nested horizontal pane reuses `TreeNavCompact`.

Use it when a layout needs a first-level switcher plus a nested tree or horizontal nav (two vertical columns, a vertical rail with a horizontal bar, a top bar with a sider, or a top bar plus two vertical columns). Prefer `STreeMenu` for a single nested sidebar and `STreeNav` for a standalone horizontal tree nav.

## Usage

Usage examples for split-nav are rendered on the site.

## Features

- 🧭 Four modes — `mode` selects the pane composition; the root switches the matching mode component
- 🎹 First-level keyboard — vertical/horizontal `useRovingFocusGroup` with Arrow, Home/End; Enter/Space activates; ArrowDown on a horizontal parent and ArrowLeft/ArrowRight on a vertical parent open the nested pane; Tab moves between panes
- 🪟 Teleport mounting — `verticalMountedId` / `horizontalMountedId` mount panes into `#id` elements (`dual-vertical` teleports as one block)
- 🪜 Path slicing — `openPath` drives nested panes; `modelValue` is the selected leaf only
- 🔄 Controlled/uncontrolled — `modelValue` / `defaultValue` store the selected leaf; clicking a parent only opens its pane, without changing `v-model` or applying the selected style
- 🌲 Expand strategy — `expandStrategy` (`keep` by default, or `selected`) is forwarded to the nested `TreeMenuCompact`
- 📢 Open event — activating a parent emits `open` with its complete option data (children included), e.g. to activate the first child at the same time
- 🧩 Reuses `TreeMenuCompact` (nested vertical) and `TreeNavCompact` (nested horizontal)
- 🙈 Hidden options — `hidden` drops an entry and its subtree from the first-level rail and from the nested panes; a parent whose children are all hidden renders as a leaf
- 🎨 6 sizes + style injection — `size` from xs to 2xl; `class` / `ui` overrides across named slots
- ✏️ Customizable — `first-level-item` / `item` / `item-leading` / `item-trailing` slots
- 🧷 Menu brand cells — `top-left` / `top-right` render above the two columns of a dual-vertical menu: the rail cell takes the rail's width, the pane cell follows that column's width and fold. The divider between the two is the pane's own leading edge — it runs that column's whole height, the brand band included — so the rail never draws one of its own. A host brand belongs inside the menu there, instead of in a region beside it
- ♿ Accessibility — `role="menubar"` / `menuitem`, `data-soybean-split-nav-*` attributes, RTL-aware `dir`

## Component family

- `SSplitNav` (styled) — entry wrapper; composes `SplitNavRoot` + `splitNavVariants` mode/size recipe + `provideSplitNavUi` slot-class injection
- `SplitNavRoot` (headless) — compact aggregator; `useControllableState` for the active value, mode switch, slot forwarding
- Internal mode components (headless) — `DualVerticalMenu`, `VerticalHorizontalMenu`, `HorizontalVerticalMenu`, `HorizontalDualVerticalMenu`
- Internal first-level menus (headless) — `VerticalFirstLevelMenu` / `HorizontalFirstLevelMenu` with shared RovingFocus items

## Demos

Interactive demos for split-nav are rendered on the site.

- 01 Basic — `dual-vertical` two vertical columns, with TreeMenu width and collapse
- 02 Vertical-Horizontal — level-1 vertical rail + nested TreeNav
- 03 Horizontal-Vertical — level-1 horizontal bar + nested TreeMenu
- 04 Horizontal-Dual-Vertical — top horizontal bar + nested dual-vertical
- 05 Teleport — mount panes into external `#id` elements
- 06 Custom — override first-level and nested item content through slots
- 07 Open Event — listen to `open` and activate the first child when a parent is clicked
- 08 Expand Strategy — switch the nested `TreeMenuCompact` between `keep` and `selected`
- 09 Top Slots — put a brand into the dual-vertical menu's `top-left` / `top-right` cells, and drop the title through the `collapsed` slot prop once the pane folds

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (2): SplitNav, SplitNavRoot.

### SplitNav

#### Props
Properties for the SplitNav component.
- `class`: Additional class names applied to the standalone dual-vertical pane. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SplitNavUi>`; optional)
- `dir`: The reading direction of the menu when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR. (type `Direction`; optional)
- `mode`: The menu shape. (type `SplitNavMode`; default `'dual-vertical'`; optional)
- `modelValue`: The selected leaf value of the SplitNav component. Can be bound with `v-model`. Parent items are not written here; clicking them only opens the nested pane. (type `string`; optional)
- `defaultValue`: The selected leaf when initially rendered. Use when you do not need to control the state. (type `string`; optional)
- `items`: The option data for the SplitNav component. (type `SplitNavOptionData<T>[]`; required)
- `horizontalMountedId`: The id of the element to mount horizontal menus into (rendered via `Teleport`). When unset, the horizontal menus render in place. Pass the element id without `#`. (type `string`; optional)
- `verticalMountedId`: The id of the element to mount vertical menus into (rendered via `Teleport`). When unset, the vertical menus render in place. Pass the element id without `#`. (type `string`; optional)
- `loop`: Whether first-level keyboard navigation loops from last item to first and vice versa. (type `boolean`; default `true`; optional)
- `expandStrategy`: The expand strategy of the nested vertical TreeMenu pane. - `keep`: keep the current expanded state; manually expanded or collapsed menus are not affected by activating other menus. The collapsible ancestors of the selected menu are expanded on mount and whenever the selected menu changes from outside (e.g. driven by an external route), so it stays visible. - `selected`: only expand the currently selected menu and all its ancestor menus; non-selected menus are collapsed when the selected menu changes. Only applies to the nested `TreeMenuCompact`; the nested horizontal pane (`TreeNavCompact`) has no expand strategy. (type `TreeMenuExpandStrategy`; default `'keep'`; optional)
- `collapsed`: Whether the nested vertical TreeMenu pane is collapsed. Can be bound with `v-model:collapsed`. (type `boolean`; optional)
- `defaultCollapsed`: The collapsed state of the nested TreeMenu pane when initially rendered. (type `boolean`; default `false`; optional)
- `collapsedWidth`: The width of the nested TreeMenu pane when it is collapsed, in pixels. (type `number`; default `50`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SplitNav component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when a leaf menu item is chosen. (type `[key: string, event?: Event | undefined]`; parameters `key: string, event?: Event | undefined`)
- `open`: Emitted when a menu item with children is activated and its nested pane opens. The payload is the complete option data of the activated parent, including children, so consumers can react to the expansion — for example, activate the first child at the same time. (type `[item: SplitNavOptionData<T>, event?: Event | undefined]`; parameters `item: SplitNavOptionData<T>, event?: Event | undefined`)
- `update:collapsed`: Emitted when the nested TreeMenu pane collapsed state changes. (type `[value: boolean]`; parameters `value: boolean`)
#### Slots
Slots for the SplitNav component.
- `first-level-item`: Custom content for a first-level item. `selected` is true for a selected leaf. `open` is true for a parent whose nested pane is showing. (type `((props: { item: SplitNavOptionData<T>; selected: boolean; open: boolean; }) => any) | undefined`)
- `top-left`: Custom content rendered above the first-level rail of a dual-vertical menu. The cell is as wide as the rail, so a brand can sit in the menu's own top-left corner instead of beside it; the divider between the two columns is the pane's own leading edge, so it runs through this band as well. `collapsed` reports whether the nested pane is folded. (type `((props: { collapsed: boolean; }) => any) | undefined`)
- `top-right`: Custom content rendered above the nested pane of a dual-vertical menu. The cell only renders while the pane column exists — the active first-level item has visible children — and follows that column's width, folded state included. `collapsed` reports whether the pane is folded. (type `((props: { collapsed: boolean; }) => any) | undefined`)
- `item`: Custom content for a nested TreeMenu / TreeNav item. (type `((props: { item: T; }) => any) | undefined`)
- `item-leading`: Custom content for a nested TreeMenu / TreeNav item leading slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trailing`: Custom content for a nested TreeMenu / TreeNav item trailing slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for a nested TreeNav item trigger icon. (type `((props: { item: T; }) => any) | undefined`)
- `item-link-icon`: Custom content for a nested TreeNav item link icon. (type `((props: { item: T; }) => any) | undefined`)

### SplitNavRoot

#### Props
Properties for the SplitNavRoot component.
- `dir`: The reading direction of the menu when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR. (type `Direction`; optional)
- `mode`: The menu shape. (type `SplitNavMode`; default `'dual-vertical'`; optional)
- `modelValue`: The selected leaf value of the SplitNav component. Can be bound with `v-model`. Parent items are not written here; clicking them only opens the nested pane. (type `string`; optional)
- `defaultValue`: The selected leaf when initially rendered. Use when you do not need to control the state. (type `string`; optional)
- `items`: The option data for the SplitNav component. (type `SplitNavOptionData<T>[]`; required)
- `horizontalMountedId`: The id of the element to mount horizontal menus into (rendered via `Teleport`). When unset, the horizontal menus render in place. Pass the element id without `#`. (type `string`; optional)
- `verticalMountedId`: The id of the element to mount vertical menus into (rendered via `Teleport`). When unset, the vertical menus render in place. Pass the element id without `#`. (type `string`; optional)
- `loop`: Whether first-level keyboard navigation loops from last item to first and vice versa. (type `boolean`; default `true`; optional)
- `expandStrategy`: The expand strategy of the nested vertical TreeMenu pane. - `keep`: keep the current expanded state; manually expanded or collapsed menus are not affected by activating other menus. The collapsible ancestors of the selected menu are expanded on mount and whenever the selected menu changes from outside (e.g. driven by an external route), so it stays visible. - `selected`: only expand the currently selected menu and all its ancestor menus; non-selected menus are collapsed when the selected menu changes. Only applies to the nested `TreeMenuCompact`; the nested horizontal pane (`TreeNavCompact`) has no expand strategy. (type `TreeMenuExpandStrategy`; default `'keep'`; optional)
- `collapsed`: Whether the nested vertical TreeMenu pane is collapsed. Can be bound with `v-model:collapsed`. (type `boolean`; optional)
- `defaultCollapsed`: The collapsed state of the nested TreeMenu pane when initially rendered. (type `boolean`; default `false`; optional)
- `collapsedWidth`: The width of the nested TreeMenu pane when it is collapsed, in pixels. (type `number`; default `50`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SplitNavRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when a leaf menu item is chosen. (type `[key: string, event?: Event | undefined]`; parameters `key: string, event?: Event | undefined`)
- `open`: Emitted when a menu item with children is activated and its nested pane opens. The payload is the complete option data of the activated parent, including children, so consumers can react to the expansion — for example, activate the first child at the same time. (type `[item: SplitNavOptionData<T>, event?: Event | undefined]`; parameters `item: SplitNavOptionData<T>, event?: Event | undefined`)
- `update:collapsed`: Emitted when the nested TreeMenu pane collapsed state changes. (type `[value: boolean]`; parameters `value: boolean`)
#### Slots
Slots for the SplitNavRoot component.
- `first-level-item`: Custom content for a first-level item. `selected` is true for a selected leaf. `open` is true for a parent whose nested pane is showing. (type `((props: { item: SplitNavOptionData<T>; selected: boolean; open: boolean; }) => any) | undefined`)
- `top-left`: Custom content rendered above the first-level rail of a dual-vertical menu. The cell is as wide as the rail, so a brand can sit in the menu's own top-left corner instead of beside it; the divider between the two columns is the pane's own leading edge, so it runs through this band as well. `collapsed` reports whether the nested pane is folded. (type `((props: { collapsed: boolean; }) => any) | undefined`)
- `top-right`: Custom content rendered above the nested pane of a dual-vertical menu. The cell only renders while the pane column exists — the active first-level item has visible children — and follows that column's width, folded state included. `collapsed` reports whether the pane is folded. (type `((props: { collapsed: boolean; }) => any) | undefined`)
- `item`: Custom content for a nested TreeMenu / TreeNav item. (type `((props: { item: T; }) => any) | undefined`)
- `item-leading`: Custom content for a nested TreeMenu / TreeNav item leading slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trailing`: Custom content for a nested TreeMenu / TreeNav item trailing slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for a nested TreeNav item trigger icon. (type `((props: { item: T; }) => any) | undefined`)
- `item-link-icon`: Custom content for a nested TreeNav item link icon. (type `((props: { item: T; }) => any) | undefined`)

## Notes

### Architecture

`SSplitNav` is a thin styled wrapper. Headless `SplitNavRoot` owns mode switching, the active path (`findActivePath`), and leaf-vs-parent selection. First-level items are a dedicated RovingFocus list — not a TreeMenu — so parent nodes switch the nested pane instead of expanding in place, and they **do not** take on the selected-leaf style. Vertical first-level items stack icon above label in a compact rail (overflowing labels ellipsize); horizontal first-level items stay icon-then-label in a row. Nested vertical content is `TreeMenuCompact` styled with `treeMenuVariants`, including a dedicated pane width, `v-model:collapsed`, and the `expandStrategy` you pass to the root; nested horizontal content is `TreeNavCompact` styled with `treeNavVariants` so it matches `STreeNav`. `class` applies to the standalone `dual-vertical` pane; mixed modes render as independent teleported fragments.

| Capability                | SoybeanUI | Ant Design | Element Plus | Naive UI |
| :------------------------ | :-------: | :--------: | :----------: | :------: |
| Multiple layout modes     |    ✅     |     ⚠️     |      ⚠️      |    —     |
| Teleport to external el   |    ✅     |     —      |      —       |    —     |
| Headless/style separation |    ✅     |     —      |      —       |    —     |
| First-level roving keys   |    ✅     |     ⚠️     |      ⚠️      |    —     |

### Cautions

- Panes render in place by default; set `horizontalMountedId` / `verticalMountedId` only when a pane must mount into an external element (pass the id without `#`).
- In `dual-vertical` and the nested dual-vertical of `horizontal-dual-vertical`, the two vertical columns teleport together via `verticalMountedId`. Mixed modes teleport the first-level and nested panes independently.
- Clicking a parent item only opens the nested pane (`data-state="open"`); it does not change `v-model` or set `data-selected`. Clicking a leaf updates `v-model` and emits `select`; the selected leaf renders `data-selected="true"` and `data-state="closed"`. A parent whose descendant is selected also gets `data-child-selected`.
- Activating a parent item (click or keyboard) emits `open` with the complete option data of that parent, children included; it fires only for parents with visible children and never for leaves.
- The nested pane keeps its own expanded state while it stays mounted, so with the default `expandStrategy="keep"` a branch you expanded under one first-level item is still expanded when you come back to it. The state resets when the pane unmounts, which happens whenever the active first-level item has no visible children.
- Flex layout per `mode` lives in the UI style recipe; the headless layer carries no layout classes.
- `top-left` / `top-right` belong to the dual-vertical shapes: the other modes render no such cells. `top-left` is the rail column's own top cell — same width as the rail — and `top-right` the pane column's, so the pane's leading divider runs through that band as well. `top-right` only exists while the pane column does, i.e. while the active first-level item has visible children. Both receive `collapsed`, so a host that renders a title there can drop it once the pane folds.
- A vertical first-level rail draws no divider of its own: the column after it leads with one. A sidebar that shows the rail alone (`vertical-horizontal`, and the dual-vertical shapes while no pane is open) therefore has no inner edge — the boundary there belongs to the layout or the container the rail sits in.
- The vertical columns of a sidebar only exist while the current state fills them. `resolveSplitNavSidebarColumns({ mode, items, modelValue, openPath })` answers which of them exist: `dual-vertical` and `horizontal-dual-vertical` use up to two columns (the latter's being the second and third level of the tree), `vertical-horizontal` keeps the rail alone in the sidebar, and `horizontal-vertical` the pane alone. A consumer that has to fix a container's width before rendering — `SAppShell` reserving its sidebar — derives it from there instead of measuring the DOM, which is unavailable during server rendering.

## FAQ

### How do I switch between the four modes?

Set the `mode` prop: `dual-vertical` (two vertical columns), `vertical-horizontal` (rail + horizontal bar), `horizontal-vertical` (horizontal bar + vertical column), or `horizontal-dual-vertical` (top bar + two vertical columns).

### How do I mount a pane into a specific element?

Give the target element an `id` and pass it to `horizontalMountedId` / `verticalMountedId`:

```vue

```

The pane is then rendered into `#app-header` / `#app-sider` through `Teleport` (`defer` keeps late-mounted targets safe).

### How do I size a container around the panes?

`resolveSplitNavSidebarColumns` reports the vertical columns a mode renders, so a container can reserve exactly their width before rendering:

```ts
import { computed } from 'vue';
import { resolveSplitNavSidebarColumns } from '@soybeanjs/headless/split-nav';

// `rail` and `pane` say whether each of the two sidebar columns exists.
const columns = computed(() => resolveSplitNavSidebarColumns({ mode, items, modelValue: active.value }));
```

Resolving from the selected value covers a container driven by the active route. Pass `openPath` as well to follow a menu that is only _opened_ — the user browsing a parent without selecting a leaf yet. `SplitNavRoot` keeps that path internal, so mirror it from the `open` event and clear it whenever the model value changes; that is what `SAppShell` does to size its layout around the columns.

### How do I know when a leaf is chosen?

The `select` event fires with the leaf value; `v-model` reflects the selected leaf only. Clicking a parent only opens the nested pane (`data-state="open"`) and does not emit `select` or set `data-selected`. If a descendant is already selected, the parent also gets `data-child-selected`.

### How do I activate the first child when a parent is clicked?

Listen to the `open` event: it carries the complete option data of the activated parent, children included. Pick its first visible child and write the value to `v-model`:

```vue
<script setup lang="ts">
import { shallowRef } from 'vue';
import { SSplitNav } from '@soybeanjs/ui';
import type { SplitNavOptionData } from '@soybeanjs/ui';

const active = shallowRef('');

function handleOpen(item: SplitNavOptionData) {
  const firstChild = item.children?.find(child => !child.hidden);

  if (firstChild) {
    active.value = firstChild.value;
  }
}
</script>

<template>
  <SSplitNav v-model="active" :items="items" @open="handleOpen" />
</template>
```

`open` fires only when a parent with visible children is activated (click or keyboard), so leaves keep using `select`.

### Can I customize each item's content?

Yes — use `first-level-item` for the first-level rail, and `item` / `item-leading` / `item-trailing` for nested TreeMenu and TreeNav items.

### Which branches stay expanded in the nested pane?

`expandStrategy` controls the nested `TreeMenuCompact` and defaults to `keep`.

- `keep` (default) — a branch you expanded by hand stays expanded: selecting another leaf, or switching first-level parents and coming back, does not collapse it. The ancestors of the selected leaf are still expanded on mount and whenever the selection changes from outside (for example when a route drives `v-model`), so the active leaf stays visible.
- `selected` — the expanded set always follows the selection: only the selected leaf and its ancestors stay expanded, and every other branch collapses as soon as the selection changes.

```vue

```

Only the nested vertical pane (`TreeMenuCompact`) has an expand strategy; the nested horizontal pane (`TreeNavCompact`) has none.

### Does it support route links?

Each node can carry `to` / `href` (inherited from `LinkBaseProps`). First-level items and nested TreeMenu / TreeNav renderers handle link rendering.

### How does first-level keyboard navigation work?

The first-level list is a `menubar`: Arrow keys move focus (vertical uses Up/Down, horizontal uses Left/Right, RTL-aware), Home/End jump to the ends, Enter/Space activates the focused item. When the item has children, ArrowDown on a horizontal rail and ArrowLeft/ArrowRight on a vertical rail open the nested pane. Nested TreeMenu and TreeNav keep their own keyboard contracts; Tab moves between panes.

## Splitter

- Page URL: /components/splitter
- Markdown URL: /components/splitter.md
- Description: A composable layout component that divides an area into resizable panels.

# Splitter

## Overview

A composable layout component that divides an area into resizable panels.

## Features

- **Three-part composition** — `SSplitterGroup` (root), `SSplitterPanel` (content region), `SSplitterResizeHandle` (drag handle between panels).
- **Horizontal and vertical directions** — `direction="horizontal" | "vertical"` flips the layout axis; cursor and ARIA orientation adapt automatically.
- **Panel size constraints** — each panel supports `defaultSize`, `minSize`, `maxSize`, and `collapsedSize` for fine-grained control over resize bounds.
- **Collapsible panels** — `collapsible` panels can collapse to `collapsedSize` via the Enter key or the imperative API, with `collapse` / `expand` / `resize` events.
- **`order` prop** — panels declare `order` to control the logical sequence for `defaultLayout` mapping and pair resizing, independent of DOM order.
- **`defaultLayout`** — provide an explicit initial layout array (maps to sorted panels by `order`).
- **Pointer dragging** — pointer-event-based dragging with `pointerId` tracking, `pointermove` / `pointerup` / `pointercancel` listeners on the owner document, and automatic cleanup on unmount.
- **Keyboard resizing** — Arrow keys resize by `keyboardResizeBy` (default 10%); Home / End jump to min / max; Enter toggles collapse.
- **RTL support** — `dir="rtl"` inverts both pointer delta and arrow-key direction for horizontal splitters; the root `dir` attribute is set from `useDirection` (falls back to `ConfigProvider`).
- **Imperative panel API** — `SSplitterPanel` exposes `collapse()`, `expand()`, `resize(size)`, `getSize()`, `isCollapsed`, and `isExpanded` via `defineExpose` for programmatic control.
- **Full ARIA separator semantics** — the handle uses `role="separator"` with `aria-controls`, `aria-orientation`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-disabled`.
- **Size scaling** — `size` (xs…2xl) scales the resize handle's visual grip width via `splitterVariants`.
- **Custom handle content** — pass a default slot to `SSplitterResizeHandle` for a fully custom grip, or use `withHandle` for the built-in dotted grip.
- **State reflection** — panels expose `data-state="collapsed|expanded"` (when collapsible), `data-panel-size`, `data-panel-collapsible`; handles expose `data-state="drag|hover|inactive"`, `data-disabled`, `data-orientation`.
- **Headless composition** — `SplitterGroup`, `SplitterPanel`, `SplitterResizeHandle` are exported from `@soybeanjs/headless/splitter` for custom styled builds.

## Usage

Usage examples for splitter are rendered on the site.

## Demo

Interactive demos for splitter are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (3): SplitterGroup, SplitterPanel, SplitterResizeHandle.

### SplitterGroup

#### Props
Properties for the SplitterGroup component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SplitterUi>`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `direction`: The orientation of the splitter group. Either `horizontal` or `vertical`. Defaults to `horizontal`. (type `DataOrientation`; optional)
- `dir`: The reading direction of the splitter group. (type `Direction`; optional)
- `defaultLayout`: The initial layout percentages for the panels. (type `number[]`; optional)
- `keyboardResizeBy`: The percentage step size used for keyboard resizing. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SplitterGroup component.
- `layout`: Event handler called when the group layout changes. (type `[value: number[]]`; parameters `value: number[]`)

### SplitterPanel

#### Props
Properties for the SplitterPanel component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `defaultSize`: The initial size of the panel as a percentage of the group. (type `number`; optional)
- `collapsible`: Whether the panel can collapse. (type `boolean`; optional)
- `collapsedSize`: The size of the panel when collapsed. (type `number`; optional)
- `maxSize`: The maximum size of the panel. (type `number`; optional)
- `minSize`: The minimum size of the panel when expanded. (type `number`; optional)
- `order`: The order of the panel within the group. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SplitterPanel component.
- `collapse`: Event handler called when the panel collapses. (type `[]`)
- `expand`: Event handler called when the panel expands. (type `[]`)
- `resize`: Event handler called when the panel size changes. (type `[size: number, prevSize: number | undefined]`; parameters `size: number, prevSize: number | undefined`)

### SplitterResizeHandle

#### Props
Properties for the SplitterResizeHandle component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `withHandle`: Whether with handle. (type `boolean`; optional)
- `disabled`: Whether the resize handle is disabled. (type `boolean`; optional)
- `tabindex`: The tabindex of the resize handle. (type `number`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the SplitterResizeHandle component.
- `dragging`: Event handler called when dragging state changes. (type `[value: boolean]`; parameters `value: boolean`)

## Notes

### Architecture and benchmark comparison

| Concern                      | SoybeanUI                                                                                  | react-resizable-panels                                  | Ant Design `ResizeBox` / `Splitter` |
| :--------------------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------ | :---------------------------------- |
| Headless / styled separation | ✅ `@soybeanjs/headless/splitter` ships logic; `@soybeanjs/ui` ships `scv()` recipe        | ❌ React-only, no headless layer                        | ❌ single styled package            |
| Panel size constraints       | `defaultSize` / `minSize` / `maxSize` / `collapsedSize`                                    | `defaultSize` / `minSize` / `maxSize` / `collapsedSize` | `min` / `max`                       |
| Collapsible panels           | `collapsible` + Enter key + imperative API                                                 | `collapsible` + `onCollapse` / `onExpand`               | —                                   |
| Panel `order`                | `order` prop controls logical sequence for layout mapping                                  | `order` prop                                            | —                                   |
| Keyboard resizing            | Arrow keys + Home / End + Enter (collapse toggle)                                          | Arrow keys + Home / End + Enter                         | —                                   |
| RTL support                  | `dir` prop + `useDirection` fallback; inverts pointer delta and arrow keys                 | `direction` prop with RTL awareness                     | —                                   |
| Imperative panel API         | `defineExpose` (`collapse` / `expand` / `resize` / `isCollapsed`)                          | `ImperativePanelHandle`                                 | —                                   |
| ARIA separator semantics     | `role="separator"` + `aria-controls` / `aria-valuenow` / `aria-valuemin` / `aria-valuemax` | same                                                    | partial                             |
| Layout persistence           | `layout` event (consumer persists)                                                         | `autoSaveId` built-in persistence                       | —                                   |
| Dynamic panel mount/unmount  | `registerPanel` / `unregisterPanel` + `refreshLayout`                                      | supported                                               | —                                   |
| Dragging event               | `dragging` event on handle                                                                 | `onDragging`                                            | —                                   |

### Runtime considerations

1. **Layout is percentage-based** — all sizes are percentages of the group's main-axis size. `getGroupSize()` reads `getBoundingClientRect()` on the group element to convert pixel delta to percentage delta during drag.
2. **`order` affects layout mapping, not DOM position** — panels are sorted by `order` for `defaultLayout` assignment and pair resizing, but their visual position is determined by template order. Use `order` when you need the layout array to map to panels in a specific logical sequence.
3. **`defaultLayout` maps to sorted panels** — when provided, `defaultLayout[i]` is assigned to the panel at sorted position `i` (by `order`, then registration index). Without `defaultLayout`, each panel uses its own `defaultSize`.
4. **Collapsible threshold** — when dragging a collapsible panel below the midpoint between `collapsedSize` and `minSize`, the panel snaps to `collapsedSize`; above the midpoint, it snaps to `minSize`.
5. **`distributeDelta` guard** — the delta distribution loop is capped at 20 iterations to prevent infinite loops when panels are tightly constrained. A fallback pass assigns any remainder to the first eligible panel.
6. **Pointer listeners are on the owner document** — `pointermove` / `pointerup` / `pointercancel` are attached to `handleElement.ownerDocument` (not the handle) so dragging continues even when the cursor leaves the handle. Listeners are cleaned up on `pointerup` / `pointercancel` and on component unmount.
7. **`useDirection` fallback** — if `dir` prop is unset, the direction falls back to `ConfigProvider`'s `dir`, then to `'ltr'`. The resolved `dir` is set on the group root element.

## FAQ

### How do I make a panel collapsible?

Set `collapsible` on `SSplitterPanel` and provide a `collapsedSize` (default `0`). Users can press Enter on the adjacent resize handle to toggle collapse. You can also call `panelRef.value.collapse()` / `expand()` programmatically.

### How does `order` work?

`order` controls the logical sequence of panels for layout calculation. `defaultLayout` array indices map to panels sorted by `order` (then by registration index for ties). This is useful when the DOM order doesn't match the desired logical order — for example, when a sidebar panel is visually first but should be logically second.

### How do I persist the layout?

Listen to the `layout` event on `SSplitterGroup` and save the array (e.g., to `localStorage`). On next mount, pass the saved array as `defaultLayout`. Unlike react-resizable-panels' `autoSaveId`, SoybeanUI leaves persistence to the consumer for flexibility.

### Can I disable a resize handle?

Yes — set `disabled` on `SSplitterResizeHandle`. The handle gets `aria-disabled="true"`, `data-disabled`, `tabindex` is removed, and pointer / keyboard interactions are blocked.

### How does RTL work?

Set `dir="rtl"` on `SSplitterGroup` (or rely on `ConfigProvider`). In RTL mode, dragging right shrinks the first panel (opposite of LTR), and ArrowLeft / ArrowRight are inverted. The root element gets `dir="rtl"`.

### How do I customize the resize handle?

Pass a default slot to `SSplitterResizeHandle` for fully custom content. Alternatively, set `withHandle` to render the built-in dotted grip. Without either, the handle is a plain line.

### Can I dynamically add or remove panels?

Yes — panels register on mount and unregister on unmount. The layout is recalculated automatically via `refreshLayout`. When a panel unmounts, its size is redistributed to the remaining panels.

## Stepper

- Page URL: /components/stepper
- Markdown URL: /components/stepper.md
- Description: Displays progress through a multi-step workflow. SStepper combines a StepperRoot-family of headless primitives (zero styles) with the stepperVariants style recipe (8 slots: root/item/trigger/indicator/indicatorIcon/itemContent/separator/title/description) and 7 colors × 7 sizes. In linear mode (the default) steps must be completed in order — future steps are disabled and cannot be skipped; in non-linear mode any step can be activated freely. The current step is announced to screen readers through a localized role="status" live region, and the group exposes an aria-label that falls back to the stepper.ariaLabel locale message.

# Stepper

## Overview

Displays progress through a multi-step workflow. `SStepper` combines a `StepperRoot`-family of headless primitives (zero styles) with the `stepperVariants` style recipe (8 slots: root/item/trigger/indicator/indicatorIcon/itemContent/separator/title/description) and 7 colors × 7 sizes. In **linear mode** (the default) steps must be completed in order — future steps are disabled and cannot be skipped; in non-linear mode any step can be activated freely. The current step is announced to screen readers through a localized `role="status"` live region, and the group exposes an `aria-label` that falls back to the `stepper.ariaLabel` locale message.

## Usage

Usage examples for stepper are rendered on the site.

## Features

- 🔁 Linear mode by default — `linear` (default `true`) disables inaccessible future steps and blocks jumping ahead; previous steps always remain reachable
- 🧭 Horizontal / vertical — `orientation` switches the layout, connector direction and arrow-key navigation axis
- 🎛️ Controlled / uncontrolled — `modelValue` + `update:modelValue` or `defaultValue` (default `1`); the root slot exposes `goToStep` / `nextStep` / `prevStep` / `hasNext` / `hasPrev` / `totalSteps` and more
- 🖱️ Click, Enter or Space to select a step; arrow keys move focus (orientation-aware, honoring `dir`), Home/End jump to the first/last reachable step
- ♿ Accessible by default — `role="group"` with a localized `aria-label` fallback, `aria-current="step"` on the active item, `aria-labelledby`/`aria-describedby` wiring between trigger/title/description, and a `role="status"` live region (`stepper.stepOf` message)
- 🧩 Headless/styled split — `StepperCompact` aggregates the 7 primitives and exposes 6 `*Props` channels (item/trigger/indicator/separator/title/description); the `step` is always derived from item order
- 🎨 8-slot styling — root/item/trigger/indicator/indicatorIcon/itemContent/separator/title/description with 7 colors (primary/destructive/success/warning/info/carbon/secondary/accent) and 7 sizes (xs–2xl)
- 🌐 Localized by default — the live region, group `aria-label` and indicator default content use `useLocaleMessages` (`stepper.step` / `stepper.ariaLabel` / `stepper.stepOf`)

## Component family

- `SStepper` (styled) — the entry wrapper; `stepperVariants` recipe with dynamic 8-slot forwarding and `useForwardListeners` event merging; mirrors the `linear` default so an absent Boolean prop is not cast to `false`
- `StepperRoot` (headless) — the state owner: `useControllableState` over `modelValue`/`defaultValue`, `totalSteps`/`currentStep` derivation, `canGoToStep` linear gating, and the `goToStep`/`nextStep`/`prevStep` API; renders `role="group"`, `data-linear`, `data-orientation`, the `aria-label` fallback and the `VisuallyHidden` live region
- `StepperItem` (headless) — `step` (1-based), `disabled`, `completed`; derives `data-state` (`completed`/`active`/`inactive`) from position and `isFocusable` from `linear` + `disabled`
- `StepperTrigger` (headless) — `button` by default; `mousedown.left` plus Enter/Space to select, arrow keys/Home/End to navigate; renders `disabled`/`data-disabled`/`tabindex="-1"` for unreachable steps and registers into the root collection
- `StepperIndicator` (headless) — `span` by default; default content is the localized `stepper.step` message (`Step {step}`)
- `StepperTitle` / `StepperDescription` (headless) — `h4`/`p` defaults; expose `id`s consumed by the trigger's `aria-labelledby`/`aria-describedby`
- `StepperSeparator` (headless) — `SeparatorRoot`-based connector; `decorative` by default, orientation and `data-state` flow from root/item context
- `StepperCompact` (headless) — the aggregated composite; normalizes items with `step: index + 1`, default indicator shows a check icon (`lucide:check` via the ConfigProvider `iconRender`) for completed steps or the step number otherwise, default title falls back to `Step {n}`; slots: `item`/`indicator`/`title`/`description`/`separator`

## Demos

Interactive demos for stepper are rendered on the site.

- 01 Basic — controlled `v-model` over `items`
- 02 Vertical — `orientation="vertical"` layout
- 03 Linear — ordered completion with Previous/Next controls
- 04 Custom styling — 8-slot `ui` overrides

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (9): Stepper, StepperCompact, StepperDescription, StepperIndicator, StepperItem, StepperRoot, StepperSeparator, StepperTitle, StepperTrigger.

### Stepper

#### Props
Properties for the Stepper component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<StepperUi>`; optional)
- `items`: Items rendered by the component. (type `StepperItemData[]`; required)
- `itemProps`: Properties forwarded to the item element. The `step` is derived from the item order and cannot be overridden. (type `Omit<StepperItemProps, 'step'>`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `StepperTriggerProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `StepperIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `SeparatorRootProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `StepperTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `StepperDescriptionProps`; optional)
- `defaultValue`: The value of the step that should be active when initially rendered. (type `number`; default `1`; optional)
- `modelValue`: The controlled value of the step to activate. Can be bind as `v-model`. (type `number`; optional)
- `orientation`: The orientation of the stepper. (type `DataOrientation`; default `'horizontal'`; optional)
- `dir`: The reading direction of the stepper. (type `Direction`; optional)
- `linear`: Whether the steps must be completed in order. (type `boolean`; default `true`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Stepper component.
- `update:modelValue`: Emitted when the model value changes. (type `[payload: number]`; parameters `payload: number`)
#### Slots
Slots for the Stepper component.
- `item`: Custom content for the item slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `indicator`: Custom content for the indicator slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)

### StepperCompact

#### Props
Properties for the StepperCompact component.
- `items`: Items rendered by the component. (type `StepperItemData[]`; required)
- `itemProps`: Properties forwarded to the item element. The `step` is derived from the item order and cannot be overridden. (type `Omit<StepperItemProps, 'step'>`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `StepperTriggerProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `StepperIndicatorProps`; optional)
- `separatorProps`: Properties forwarded to the separator element. (type `SeparatorRootProps`; optional)
- `titleProps`: Properties forwarded to the title element. (type `StepperTitleProps`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `StepperDescriptionProps`; optional)
- `defaultValue`: The value of the step that should be active when initially rendered. (type `number`; default `1`; optional)
- `modelValue`: The controlled value of the step to activate. Can be bind as `v-model`. (type `number`; optional)
- `orientation`: The orientation of the stepper. (type `DataOrientation`; default `'horizontal'`; optional)
- `dir`: The reading direction of the stepper. (type `Direction`; optional)
- `linear`: Whether the steps must be completed in order. (type `boolean`; default `true`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the StepperCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[payload: number]`; parameters `payload: number`)
#### Slots
Slots for the StepperCompact component.
- `item`: Custom content for the item slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `indicator`: Custom content for the indicator slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `title`: Custom content for the title slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `description`: Custom content for the description slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `((props: StepperItemData & { step: number; state: StepperState; }) => any) | undefined`)

### StepperDescription

#### Props
Properties for the StepperDescription component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### StepperIndicator

#### Props
Properties for the StepperIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### StepperItem

#### Props
Properties for the StepperItem component.
- `step`: The step index, starting from `1`. (type `number`; required)
- `disabled`: When `true`, prevents the user from interacting with the step. (type `boolean`; optional)
- `completed`: Shows whether the step is completed. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### StepperRoot

#### Props
Properties for the StepperRoot component.
- `defaultValue`: The value of the step that should be active when initially rendered. (type `number`; default `1`; optional)
- `modelValue`: The controlled value of the step to activate. Can be bind as `v-model`. (type `number`; optional)
- `orientation`: The orientation of the stepper. (type `DataOrientation`; default `'horizontal'`; optional)
- `dir`: The reading direction of the stepper. (type `Direction`; optional)
- `linear`: Whether the steps must be completed in order. (type `boolean`; default `true`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the StepperRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[payload: number]`; parameters `payload: number`)

### StepperSeparator

#### Props
Properties for the StepperSeparator component.
- `orientation`: Orientation of the component. Either `vertical` or `horizontal`. Defaults to `horizontal`. (type `DataOrientation`; optional)
- `decorative`: Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. (type `boolean`; optional)

### StepperTitle

#### Props
Properties for the StepperTitle component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### StepperTrigger

#### Props
Properties for the StepperTrigger component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`StepperRoot` owns the whole state machine (controllable state, ordered item collection, linear gating) while every primitive stays style-free and only the UI wrapper injects the `stepperVariants` classes. `isFocusable` is derived per item (`disabled || (!linear && step > currentStep + 1)`) and mirrored into the DOM as `disabled`/`data-disabled`/`tabindex`, so unreachable steps are both non-clickable and out of the tab order. Arrow navigation uses `useArrowNavigation` with `loop: false` and respects `orientation`/`dir`; in linear mode focus cannot land on a disabled future step. The completed check icon requires a ConfigProvider `iconRender` (default: the `Icon` component renders nothing), otherwise completed steps fall back to their number. The live region and `aria-label` fallback are localized via `useLocaleMessages`, unlike shadcn/ui's stepper block which hardcodes English strings.

| Capability                                 | SoybeanUI | shadcn/ui (blocks) | Ant Design Steps | Element Plus Steps | Mantine Stepper |
| :----------------------------------------- | :-------: | :----------------: | :--------------: | :----------------: | :-------------: |
| headless/styled split                      |    ✅     |         —          |        —         |         —          |        —        |
| Linear mode (ordered completion)           |    ✅     |         ✅         |        ⚠️        |         ✅         |       ✅        |
| Orientation (horizontal/vertical)          |    ✅     |         ✅         |        ✅        |         ✅         |       ✅        |
| Arrow-key navigation (Home/End)            |    ✅     |         —          |        —         |         —          |        —        |
| Localized live region + group `aria-label` |    ✅     |         ⚠️         |        —         |         —          |        —        |
| Controlled/uncontrolled                    |    ✅     |         —          |        ⚠️        |         ⚠️         |       ✅        |
| Compact composite with per-part props      |    ✅     |         —          |        —         |         —          |        —        |
| `completed`/`disabled` per step            |    ✅     |         ✅         |        ✅        |         ✅         |       ✅        |

`⚠️` = partial (AntD uses a `status` prop instead of a linear gate; Element Plus exposes `process-status`/`finish-status` without a navigation gate; shadcn/ui's stepper block renders the status text with hardcoded English and is not a library component).

### Cautions

- `step` on `StepperItem` must be 1-based and sequential: `canGoToStep` and the focus logic index the ordered collection by `step - 1`. The compact normalizes this automatically from item order; custom headless compositions must keep steps contiguous.
- `itemProps` intentionally omits `step` — it is derived from item order and cannot be overridden.
- In linear mode only the current step and the next one are reachable; `goToStep`/`nextStep` silently ignore unreachable targets, so drive navigation through `hasNext`/`hasPrev` or the `nextStep`/`prevStep` helpers.
- The live region (`role="status"`) only renders when `totalSteps > 0`; give the root an explicit `aria-label` when the default locale message is not appropriate.
- The default indicator falls back to the step number when no ConfigProvider `iconRender` is present; provide one to render the completed check icon.
- `disabled` steps are skipped by arrow navigation but the collection is still ordered; a fully disabled stepper should still expose the group `aria-label`.

## FAQ

### How do I make future steps clickable?

Set `linear="false"` — every step becomes focusable and selectable regardless of the current position:

```vue

```

### How do I drive the stepper with buttons?

Listen to the root slot helpers or simply bind `v-model` and use `hasNext`/`hasPrev` from the root slot to gate your controls:

```vue

  <template #default="{ hasNext, hasPrev, nextStep, prevStep }">
    
  </template>

```

### How do I render a vertical stepper?

Set `orientation="vertical"` — the connector and arrow-key navigation axis follow:

```vue

```

### How do I mark a step as completed regardless of position?

Pass `completed` in the item data; an explicit `completed` wins over position-derived state:

```vue

```

### How do I customize the indicator content?

Use the `indicator` slot — it receives the item data, step and state:

```vue

  <template #indicator="{ state, step }">
    <span>{{ state === 'completed' ? '✓' : step }}</span>
  </template>

```

### How do I localize the status announcement?

The live region and group `aria-label` follow the ConfigProvider locale (`stepper.stepOf` / `stepper.ariaLabel`); override the label per-instance with `aria-label`:

```vue

```

## Switch

- Page URL: /components/switch
- Markdown URL: /components/switch.md
- Description: A control that toggles between checked and unchecked states with a sliding thumb and native form integration. Use it for a single binary setting that takes effect immediately (e.g. dark mode, notifications); when the option belongs to a form that needs explicit submission, prefer SCheckbox; when more than one value can be selected, use a checkbox group instead.

# Switch

## Overview

A control that toggles between checked and unchecked states with a sliding thumb and native form integration. Use it for a single binary setting that takes effect immediately (e.g. dark mode, notifications); when the option belongs to a form that needs explicit submission, prefer `SCheckbox`; when more than one value can be selected, use a checkbox group instead.

## Usage

Usage examples for switch are rendered on the site.

## Features

- 🎚 `modelValue` / `defaultValue` — controlled and uncontrolled modes backed by `useControllableState`
- 🅰 Custom values — `trueValue` / `falseValue` accept booleans, strings, or numbers
- ⌨️ Keyboard operable — Enter and Space toggle the switch (native button behavior)
- ♿ `role="switch"` + `aria-checked` / `data-state` dual reflection, axe-clean
- 📋 Native form proxy — a visually hidden checkbox input carries `name` / `required` / `value`
- 🎨 6 sizes, 8 colors, and rounded/square shapes via `switchVariants`
- 🧩 `leading` / `trailing` / default (thumb) slots for labels and icons
- ↔ RTL-aware thumb animation driven by `dir`

## Demos

Interactive demos for switch are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Switch, SwitchCompact, SwitchControl, SwitchRoot, SwitchThumb.

### Switch

#### Props
Properties for the Switch component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SwitchUi>`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `shape`: Shape of the component. (type `SwitchShape`; optional)
- `controlProps`: Properties forwarded to the control element. (type `SwitchControlProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `SwitchThumbProps`; optional)
- `defaultValue`: The state of the switch when it is initially rendered. Use when you do not need to control its state. (type `NonNullable<T>`; optional)
- `modelValue`: The controlled state of the switch. Can be bind as `v-model`. (type `T`; optional)
- `disabled`: When `true`, prevents the user from interacting with the switch. (type `boolean`; optional)
- `value`: The value given as data when submitted with a `name`. (type `string`; optional)
- `dir`: The direction the switch should animate towards when changing state. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `trueValue`: The value given as data when submitted with a `name`. (type `NonNullable<T>`; default `true`; optional)
- `falseValue`: The value given as data when submitted with a `name`. (type `NonNullable<T>`; default `false`; optional)
#### Emits
Events for the Switch component.
- `update:modelValue`: Event handler called when the value of the switch changes. (type `[payload: NonNullable<T>]`; parameters `payload: NonNullable<T>`)
#### Slots
Slots for the Switch component.
- `default`: Custom content for the default slot. (type `((props: SwitchCompactSlotProps<T>) => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `((props: SwitchCompactSlotProps<T>) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: SwitchCompactSlotProps<T>) => any) | undefined`)

### SwitchCompact

#### Props
Properties for the SwitchCompact component.
- `controlProps`: Properties forwarded to the control element. (type `SwitchControlProps`; optional)
- `thumbProps`: Properties forwarded to the thumb element. (type `SwitchThumbProps`; optional)
- `defaultValue`: The state of the switch when it is initially rendered. Use when you do not need to control its state. (type `NonNullable<T>`; optional)
- `modelValue`: The controlled state of the switch. Can be bind as `v-model`. (type `T`; optional)
- `disabled`: When `true`, prevents the user from interacting with the switch. (type `boolean`; optional)
- `value`: The value given as data when submitted with a `name`. (type `string`; optional)
- `dir`: The direction the switch should animate towards when changing state. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `trueValue`: The value given as data when submitted with a `name`. (type `NonNullable<T>`; default `true`; optional)
- `falseValue`: The value given as data when submitted with a `name`. (type `NonNullable<T>`; default `false`; optional)
#### Emits
Events for the SwitchCompact component.
- `update:modelValue`: Event handler called when the value of the switch changes. (type `[payload: NonNullable<T>]`; parameters `payload: NonNullable<T>`)
#### Slots
Slots for the SwitchCompact component.
- `default`: Custom content for the default slot. (type `((props: SwitchCompactSlotProps<T>) => any) | undefined`)
- `leading`: Custom content for the leading slot. (type `((props: SwitchCompactSlotProps<T>) => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `((props: SwitchCompactSlotProps<T>) => any) | undefined`)
#### Slot Props
Slot properties for the SwitchCompact component.
- `modelValue`: Current model value. (type `T | undefined`; required)

### SwitchControl

#### Props
Properties for the SwitchControl component.
- `id`: Id of the element (type `string`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### SwitchRoot

#### Props
Properties for the SwitchRoot component.
- `defaultValue`: The state of the switch when it is initially rendered. Use when you do not need to control its state. (type `NonNullable<T>`; optional)
- `modelValue`: The controlled state of the switch. Can be bind as `v-model`. (type `T`; optional)
- `disabled`: When `true`, prevents the user from interacting with the switch. (type `boolean`; optional)
- `value`: The value given as data when submitted with a `name`. (type `string`; optional)
- `dir`: The direction the switch should animate towards when changing state. (type `Direction`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `trueValue`: The value given as data when submitted with a `name`. (type `NonNullable<T>`; default `true`; optional)
- `falseValue`: The value given as data when submitted with a `name`. (type `NonNullable<T>`; default `false`; optional)
#### Emits
Events for the SwitchRoot component.
- `update:modelValue`: Event handler called when the value of the switch changes. (type `[payload: NonNullable<T>]`; parameters `payload: NonNullable<T>`)

### SwitchThumb

#### Props
Properties for the SwitchThumb component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

SoybeanUI builds the switch from headless `SwitchRoot` (`useControllableState` + `VisuallyHiddenInput` form proxy) → `SwitchControl` (`Button` base + `role="switch"` + `aria-checked`/`data-state`, disabled-guarded) → `SwitchThumb` (`Primitive` + `data-state`/`data-disabled`). `SwitchCompact` composes root + control + thumb, owns the `leading`/`trailing` slots, and generates the control id; the UI wrapper `SSwitch` only computes variant classes via `switchVariants` and injects the `ui` map through `provideSwitchUi`.

| Capability                          | SoybeanUI | Ant Design `Switch` | Element Plus `Switch` | Mantine `Switch` | Naive UI `Switch` | shadcn `Switch` |
| :---------------------------------- | :-------: | :-----------------: | :-------------------: | :--------------: | :---------------: | :-------------: |
| headless/styled split               |    ✅     |          —          |           —           |        —         |         —         |       ✅        |
| Controlled/uncontrolled             |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Custom on/off values                |    ✅     |         ✅          |          ✅           |        —         |        ✅         |       ✅        |
| Leading/trailing slots              |    ✅     |          —          |          ✅           |        ✅        |         —         |        —        |
| `loading` state                     |    ➕     |         ✅          |          ✅           |        ✅        |        ✅         |        —        |
| Inline label (`onLabel`/`offLabel`) |    ➕     |          —          |          ✅           |        ✅        |         —         |        —        |
| `beforeChange` hook                 |    ➕     |          —          |          ✅           |        —         |         —         |        —        |
| Form proxy / `name` submit          |    ✅     |         ✅          |          ✅           |        ✅        |        ✅         |       ✅        |
| Axe-clean                           |    ✅     |          —          |           —           |        —         |         —         |        —        |

### Cautions

- The control is a `<button role="switch">` — provide an accessible name via `controlProps` (`aria-label`) or a visible label when used standalone.
- `trueValue` / `falseValue` must not be nullish; a runtime guard throws otherwise.
- The visually hidden input submits `value` (default `'on'`) when checked — it is independent of `trueValue`.
- The form proxy renders only when `name` is present on a `form`-classed root; pair it with a native `<form>` or the `SForm` integration.

## FAQ

### Controlled or uncontrolled?

Pass `modelValue` with `v-model` for a controlled value, or `defaultValue` to let the switch own its state internally. Both are supported via `useControllableState`.

### Can I use non-boolean values?

Yes — set `trueValue` / `falseValue` to any string or number (e.g. `'on'` / `'off'`); `aria-checked` and `data-state` reflect the comparison against `trueValue`.

### How do I add a label next to the switch?

Use the `leading` / `trailing` slots, or pair a native `<label>` with the control `id`.

### How does the switch submit its value in a form?

Give the switch a `name`; inside a `form`-classed root a visually hidden checkbox input is rendered and carries the submitted `value` when the switch is checked.

## Table

- Page URL: /components/table
- Markdown URL: /components/table.md
- Description: A data table component for displaying row and column data. STable combines the headless TableCompact aggregation component (9 zero-style base primitives in the TableRoot family) with the tableVariants style recipe (29 slots, 7 sizes × 2 visual variants). Supports a config-driven columns model (grouped headers, index/selection/expand type columns), sorting, filtering, multi/single selection, expandable and tree rows, fixed columns/headers, drag-and-keyboard column resizing, virtualization, and empty states; default/simple variants plus bordered/rounded/striped toggles. All interaction text and aria-labels (sorting, filtering, selection, expansion, column resize) are localized via useLocaleMessages.

# Table

## Overview

A data table component for displaying row and column data. `STable` combines the headless `TableCompact` aggregation component (9 zero-style base primitives in the `TableRoot` family) with the `tableVariants` style recipe (29 slots, 7 sizes × 2 visual variants). Supports a **config-driven `columns` model** (grouped headers, `index`/`selection`/`expand` type columns), sorting, filtering, multi/single selection, expandable and tree rows, fixed columns/headers, drag-and-keyboard column resizing, virtualization, and empty states; `default`/`simple` variants plus `bordered`/`rounded`/`striped` toggles. All interaction text and `aria-label`s (sorting, filtering, selection, expansion, column resize) are localized via `useLocaleMessages`.

## Usage

Usage examples for table are rendered on the site.

## Features

- 📋 Config-driven columns — TanStack-first `columns: TableColumn<T>[]` (`accessorKey`/`header`/`size`/`minSize` + SoybeanUI `align`/`type`/`fixed`/`hidden` extensions), grouped headers (`columns`), `index`/`selection`/`expand` type columns; `rowKey` keeps row identity stable
- 🔀 Sorting — `enableSorting: true` (or `sortFn` comparator) on a column; controlled `sorting` / `v-model:sorting` (TanStack `SortingState`); `aria-sort` + localized sort-button `aria-label`
- 🔍 Filtering — `enableColumnFilter: true` (+ `filterPlaceholder`/`filterOptions`); compound `{ keyword, values }` filter values, keyword search, option multi-select, summary count, and clear action are all localized; state is TanStack `ColumnFiltersState` (`v-model:columnFilters`)
- ✅ Selection — multi-select by default (`multiple` defaults to `true`, checkboxes + header select-all); `multiple={false}` switches to single-select (row radio); controlled `selected` / `v-model:selected`
- 🧩 Expandable & tree rows — `expand` type column or the `expanded-row` slot renders expanded rows; `children`/`getChildren` drive tree rows (engine `getSubRows`); `expanded` follows TanStack `ExpandedState`
- 📐 Fixed & resizable — `fixed: 'start' | 'end'` seeds TanStack column pinning with gradient shadow indicators; `resizable` columns support pointer drag and arrow-key resizing writing TanStack `columnSizing` (localized `aria-label`)
- ⚡ Performance — `virtual` + `height` enable virtualization (custom `estimateSize`/`virtualizerOptions`), rendering only visible rows
- 🎛️ Engine escape hatch — slot props carry `table`/`engineColumn` engine instances, `useTableEngine()` injects the engine anywhere inside the table subtree, the template ref exposes `table`, and the `tableOptions` prop passes raw TanStack options through (pagination, row selection, manual modes, meta, `initialState`...)
- 🌐 Localized by default — empty state, sort/filter/select/expand/resize `aria-label`s, and the filter popover copy all use `useLocaleMessages` (21 `table.*` messages across 14 language packs)

## Component family

- `STable` (styled) — entry wrapper; `tableVariants` recipe (29 slots = 16 headless slots + 11 filter/selection extra slots + 2 internal radio slots); `useOmitProps` forwarding + `useForwardListeners` event merging + full slot passthrough; injects default `header-selection`/`selection`/`header-sort`/`header-filter`/`header-resize`/`tree-toggle`/`expand`/`empty` slot content
- `TableCompact` (headless) — aggregation state owner over the **`@tanstack/vue-table` engine**: `useTableCompactState` (`sorting`/`columnFilters`/`expanded`/`columnPinning`/`columnSizing` via `useControllableState`, `selected`/`multiple` via `useSelection`), `useTableCompactTable` (engine instance wiring), `useTableCompactData` (header groups/leaf columns/row model), `useTableCompactResize` (pointer + keyboard column widths), `useTableCompactVirtual`; `provideTableCompactContext` bridges the 9 primitives
- `TableRoot` (headless) — root element, `dir` direction, renders `data-soybean-table-root` and the table semantic container
- `TableScroll` / `TableContent` / `TableHeader` / `TableBody` / `TableFooter` / `TableRow` / `TableHead` / `TableCell` (headless) — 9 base primitives, all zero-style, each rendering `data-soybean-table-*` data attributes
- `TableCompactHead` / `TableCompactRow` / `TableCompactCell` / `TableCompactExpandedRow` / `TableVirtualSpacerRow` (headless internal) — composition and rendering components inside the Compact aggregation (not publicly exported)
- `STableFilterPopover` (styled internal) — the filter popover (SPopover + SInput + SCheckbox + SButton) with localized search/options/summary/clear
- `STableRadio` (styled internal) — the row radio used in single-select mode (`aria-pressed` semantics), consuming the `radioRoot`/`radioIndicator` recipe slots directly
- `useTable` / `usePaginatedTable` (UI hooks) — client-side sort/filter/pagination composition hooks

## Demos

Interactive demos for table are rendered on the site.

- 01 Basic — plain `columns` + `data` rendering
- 02 Variant — `default` / `simple` visual variants
- 03 Bordered — `bordered` toggle
- 04 Rounded — `rounded` toggle
- 05 Striped — `striped` zebra rows
- 06 Empty — empty state (default `SEmpty` and custom `empty` slot)
- 07 Grouped — grouped headers (`columns`)
- 08 Sorting — `enableSorting` + `sortFn` with controlled/uncontrolled sorting
- 09 Filtering — `enableColumnFilter` options and the keyword filter popover
- 10 Fixed — `fixed: 'start' | 'end'` fixed columns
- 11 Resizable — `resizable` drag/keyboard column resize
- 12 Tree — tree rows (`children` data + `tree-toggle`)
- 13 Virtualized — `virtual` + `height` virtualization
- 14 Expandable — `expand` column and `expanded-row` slot
- 15 Footer — `footer` summary slot
- 16 Bottom — `bottom` slot
- 17 Multiple Selection — multi-select (checkboxes + select-all)
- 18 Single Selection — `multiple={false}` single-select (radio)
- 19 Row Events — `rowClick`/`rowDblclick`/`rowContextmenu` row events
- 20 Sizes — 7 sizes (xs–2xl)

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (29): Table, TableBody, TableCell, TableCompact, TableCompactCell, TableCompactExpandedRow, TableCompactHead, TableCompactRow, TableContent, TableDataCell, TableEmpty, TableExpand, TableExpandedRow, TableFilterPopover, TableFooter, TableHead, TableHeader, TableHeaderFilter, TableHeaderResize, TableHeaderSelection, TableHeaderSort, TableIndex, TableRadio, TableRoot, TableRow, TableScroll, TableSelection, TableTreeToggle, TableVirtualSpacerRow.

### Table

#### Props
Properties for the Table component.
- `class`: Additional class names to apply to the table. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TableExtendedUi>`; optional)
- `variant`: Visual variant of the component. (type `TableVariant`; optional)
- `bordered`: Whether bordered. (type `boolean`; optional)
- `rounded`: Whether rounded. (type `boolean`; optional)
- `striped`: Whether striped. (type `boolean`; optional)
- `columns`: Column definitions. TanStack column defs are the first citizens. (type `TableColumn<T>[]`; required)
- `data`: Data. (type `T[]`; required)
- `rowKey`: Row key. (type `(row: T) => R`; required)
- `getChildren`: Nested children resolver used as the engine `getSubRows`. (type `((row: T) => T[])`; optional)
- `sorting`: Sorting state (TanStack `SortingState`). (type `SortingState`; optional)
- `defaultSorting`: Default sorting state. (type `SortingState`; optional)
- `tableOptions`: Engine options passed through to the TanStack `useTable` call. Keys the component owns (data, columns, state wiring, owned change handlers) are overridden by the component; everything else unlocks the full engine surface (pagination, row selection, manual modes, meta, initialState...). (type `TableEngineOptions`; optional)
- `columnFilters`: Column filters state (TanStack `ColumnFiltersState`). Filter values accept the compound `{ keyword, values }` shape handled by the built-in filter. (type `ColumnFiltersState`; optional)
- `defaultColumnFilters`: Default column filters state. (type `ColumnFiltersState`; optional)
- `expanded`: Expanded state (TanStack `ExpandedState`). (type `ExpandedState`; optional)
- `defaultExpanded`: Default expanded state. (type `ExpandedState`; optional)
- `defaultExpandAll`: Whether to expand all rows by default. (type `boolean`; optional)
- `columnPinning`: Column pinning state (TanStack `ColumnPinningState`). Column `fixed` fields seed the default state when this prop is absent. (type `ColumnPinningState`; optional)
- `defaultColumnPinning`: Default column pinning state. (type `ColumnPinningState`; optional)
- `columnSizing`: Column sizing state (TanStack `ColumnSizingState`, px keyed by column id). (type `ColumnSizingState`; optional)
- `defaultColumnSizing`: Default column sizing state. (type `ColumnSizingState`; optional)
- `indent`: Indent width applied to nested items. (type `number`; optional)
- `virtual`: Whether virtual. (type `boolean`; optional)
- `height`: Height. (type `string | number`; optional)
- `estimateSize`: Estimate size. (type `number | ((index: number, row: T) => number)`; optional)
- `virtualizerOptions`: Virtualizer options. (type `VirtualizerOptions`; optional)
- `contentProps`: Properties forwarded to the content element. (type `TableContentProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `TableHeaderProps`; optional)
- `bodyProps`: Properties forwarded to the body element. (type `TableBodyProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `TableFooterProps`; optional)
- `headProps`: Properties forwarded to the head element. (type `TableHeadProps`; optional)
- `rowProps`: Properties forwarded to the row element. (type `TableRowProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `TableCellProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `defaultSelected`: Default selected. (type `(M extends true ? R[] : R)`; optional)
- `selected`: Whether the item is selected. (type `(M extends true ? R[] : R)`; optional)
- `multiple`: Whether multiple values are supported. (type `M`; optional)
#### Emits
Events for the Table component.
- `update:sorting`: Emitted when the sorting state value changes. (type `[state: SortingState]`; parameters `state: SortingState`)
- `update:columnFilters`: Emitted when the column filters state value changes. (type `[state: ColumnFiltersState]`; parameters `state: ColumnFiltersState`)
- `update:expanded`: Emitted when the expanded state value changes. (type `[state: ExpandedState]`; parameters `state: ExpandedState`)
- `update:columnPinning`: Emitted when the column pinning state value changes. (type `[state: ColumnPinningState]`; parameters `state: ColumnPinningState`)
- `update:columnSizing`: Emitted when the column sizing state value changes. (type `[state: ColumnSizingState]`; parameters `state: ColumnSizingState`)
- `update:selected`: Emitted when the selected state changes. (type `[selected: M extends true ? R[] : R | undefined]`; parameters `selected: M extends true ? R[] : R | undefined`)
- `rowClick`: Emitted when a row is clicked. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowDblclick`: Emitted when a row is double clicked. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowContextmenu`: Emitted when a row context menu is triggered. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowMouseenter`: Emitted when the pointer enters a row. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowMouseleave`: Emitted when the pointer leaves a row. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
#### Slots
Slots for the Table component.
- `bottom`: Custom content for the bottom slot. (type `(() => any) | undefined`)
- `header`: Custom content for the header slot. (type `((props: TableHeaderSlotProps<T>) => any) | undefined`)
- `header-index`: Custom content for the header index slot. (type `((props: { column: TableColumn<T>; }) => any) | undefined`)
- `header-selection`: Custom content for the header selection slot. (type `((props: TableHeaderSelectionSlotProps<T>) => any) | undefined`)
- `header-expand`: Custom content for the header expand slot. (type `((props: { column: TableColumn<T>; }) => any) | undefined`)
- `header-filter`: Custom content for the header filter slot. (type `((props: TableHeaderFilterSlotProps<T>) => any) | undefined`)
- `header-sort`: Custom content for the header sort slot. (type `((props: TableHeaderSortSlotProps<T>) => any) | undefined`)
- `header-resize`: Custom content for the header resize slot. (type `((props: TableHeaderResizeSlotProps<T>) => any) | undefined`)
- `index`: Custom content for the index slot. (type `((props: TableIndexSlotProps<T>) => any) | undefined`)
- `selection`: Custom content for the selection slot. (type `((props: TableSelectionSlotProps<T>) => any) | undefined`)
- `expand`: Custom content for the expand slot. (type `((props: TableExpandSlotProps<T>) => any) | undefined`)
- `expanded-row`: Custom content for the expanded row slot. (type `((props: TableExpandedRowSlotProps<T>) => any) | undefined`)
- `tree-toggle`: Custom content for the tree toggle slot. (type `((props: TableTreeToggleSlotProps<T>) => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `((props: TableEmptySlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: { columnSize: number; }) => any) | undefined`)

### TableBody

- No documented props, emits, slots, or slot props were available.

### TableCell

#### Slot Props
Slot properties for the TableCell component.
- `index`: Index of the current item. (type `number`; required)
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `engineColumn`: Engine column instance exposed in the slot scope. (type `TableEngineColumn<T>`; optional)
- `table`: Engine table instance exposed in the slot scope (full TanStack API). (type `TableEngineTable<T>`; optional)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)
- `expanded`: Whether expanded. (type `boolean`; required)
- `toggleExpand`: Toggle expand exposed in the slot scope. (type `() => void`; required)

### TableCompact

#### Props
Properties for the TableCompact component.
- `columns`: Column definitions. TanStack column defs are the first citizens. (type `TableColumn<T>[]`; required)
- `data`: Data. (type `T[]`; required)
- `rowKey`: Row key. (type `(row: T) => R`; required)
- `getChildren`: Nested children resolver used as the engine `getSubRows`. (type `((row: T) => T[])`; optional)
- `sorting`: Sorting state (TanStack `SortingState`). (type `SortingState`; optional)
- `defaultSorting`: Default sorting state. (type `SortingState`; optional)
- `tableOptions`: Engine options passed through to the TanStack `useTable` call. Keys the component owns (data, columns, state wiring, owned change handlers) are overridden by the component; everything else unlocks the full engine surface (pagination, row selection, manual modes, meta, initialState...). (type `TableEngineOptions`; optional)
- `columnFilters`: Column filters state (TanStack `ColumnFiltersState`). Filter values accept the compound `{ keyword, values }` shape handled by the built-in filter. (type `ColumnFiltersState`; optional)
- `defaultColumnFilters`: Default column filters state. (type `ColumnFiltersState`; optional)
- `expanded`: Expanded state (TanStack `ExpandedState`). (type `ExpandedState`; optional)
- `defaultExpanded`: Default expanded state. (type `ExpandedState`; optional)
- `defaultExpandAll`: Whether to expand all rows by default. (type `boolean`; optional)
- `columnPinning`: Column pinning state (TanStack `ColumnPinningState`). Column `fixed` fields seed the default state when this prop is absent. (type `ColumnPinningState`; optional)
- `defaultColumnPinning`: Default column pinning state. (type `ColumnPinningState`; optional)
- `columnSizing`: Column sizing state (TanStack `ColumnSizingState`, px keyed by column id). (type `ColumnSizingState`; optional)
- `defaultColumnSizing`: Default column sizing state. (type `ColumnSizingState`; optional)
- `indent`: Indent width applied to nested items. (type `number`; optional)
- `virtual`: Whether virtual. (type `boolean`; optional)
- `height`: Height. (type `string | number`; optional)
- `estimateSize`: Estimate size. (type `number | ((index: number, row: T) => number)`; optional)
- `virtualizerOptions`: Virtualizer options. (type `VirtualizerOptions`; optional)
- `contentProps`: Properties forwarded to the content element. (type `TableContentProps`; optional)
- `headerProps`: Properties forwarded to the header element. (type `TableHeaderProps`; optional)
- `bodyProps`: Properties forwarded to the body element. (type `TableBodyProps`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `TableFooterProps`; optional)
- `headProps`: Properties forwarded to the head element. (type `TableHeadProps`; optional)
- `rowProps`: Properties forwarded to the row element. (type `TableRowProps`; optional)
- `cellProps`: Properties forwarded to the cell element. (type `TableCellProps`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `defaultSelected`: Default selected. (type `(M extends true ? R[] : R)`; optional)
- `selected`: Whether the item is selected. (type `(M extends true ? R[] : R)`; optional)
- `multiple`: Whether multiple values are supported. (type `M`; optional)
#### Emits
Events for the TableCompact component.
- `update:sorting`: Emitted when the sorting state value changes. (type `[state: SortingState]`; parameters `state: SortingState`)
- `update:columnFilters`: Emitted when the column filters state value changes. (type `[state: ColumnFiltersState]`; parameters `state: ColumnFiltersState`)
- `update:expanded`: Emitted when the expanded state value changes. (type `[state: ExpandedState]`; parameters `state: ExpandedState`)
- `update:columnPinning`: Emitted when the column pinning state value changes. (type `[state: ColumnPinningState]`; parameters `state: ColumnPinningState`)
- `update:columnSizing`: Emitted when the column sizing state value changes. (type `[state: ColumnSizingState]`; parameters `state: ColumnSizingState`)
- `update:selected`: Emitted when the selected state changes. (type `[selected: M extends true ? R[] : R | undefined]`; parameters `selected: M extends true ? R[] : R | undefined`)
- `rowClick`: Emitted when a row is clicked. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowDblclick`: Emitted when a row is double clicked. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowContextmenu`: Emitted when a row context menu is triggered. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowMouseenter`: Emitted when the pointer enters a row. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
- `rowMouseleave`: Emitted when the pointer leaves a row. (type `[event: MouseEvent, payload: TableRowEventPayload<T, R>]`; parameters `event: MouseEvent, payload: TableRowEventPayload<T, R>`)
#### Slots
Slots for the TableCompact component.
- `bottom`: Custom content for the bottom slot. (type `(() => any) | undefined`)
- `header`: Custom content for the header slot. (type `((props: TableHeaderSlotProps<T>) => any) | undefined`)
- `header-index`: Custom content for the header index slot. (type `((props: { column: TableColumn<T>; }) => any) | undefined`)
- `header-selection`: Custom content for the header selection slot. (type `((props: TableHeaderSelectionSlotProps<T>) => any) | undefined`)
- `header-expand`: Custom content for the header expand slot. (type `((props: { column: TableColumn<T>; }) => any) | undefined`)
- `header-filter`: Custom content for the header filter slot. (type `((props: TableHeaderFilterSlotProps<T>) => any) | undefined`)
- `header-sort`: Custom content for the header sort slot. (type `((props: TableHeaderSortSlotProps<T>) => any) | undefined`)
- `header-resize`: Custom content for the header resize slot. (type `((props: TableHeaderResizeSlotProps<T>) => any) | undefined`)
- `index`: Custom content for the index slot. (type `((props: TableIndexSlotProps<T>) => any) | undefined`)
- `selection`: Custom content for the selection slot. (type `((props: TableSelectionSlotProps<T>) => any) | undefined`)
- `expand`: Custom content for the expand slot. (type `((props: TableExpandSlotProps<T>) => any) | undefined`)
- `expanded-row`: Custom content for the expanded row slot. (type `((props: TableExpandedRowSlotProps<T>) => any) | undefined`)
- `tree-toggle`: Custom content for the tree toggle slot. (type `((props: TableTreeToggleSlotProps<T>) => any) | undefined`)
- `empty`: Custom content for the empty slot. (type `((props: TableEmptySlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: { columnSize: number; }) => any) | undefined`)

### TableCompactCell

#### Props
Properties for the TableCompactCell component.
- `column`: Column definition. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `row`: Row. (type `TableTreeRow<TableBaseData, TableUnifiedKey>`; required)
- `index`: Index of the current item. (type `number`; required)
#### Slots
Slots for the TableCompactCell component.
- `index`: Custom content for the index slot. (type `((props: TableIndexSlotProps<T>) => any) | undefined`)
- `selection`: Custom content for the selection slot. (type `((props: TableSelectionSlotProps<T>) => any) | undefined`)
- `expand`: Custom content for the expand slot. (type `((props: TableExpandSlotProps<T>) => any) | undefined`)
- `tree-toggle`: Custom content for the tree toggle slot. (type `((props: TableTreeToggleSlotProps<T>) => any) | undefined`)

### TableCompactExpandedRow

#### Props
Properties for the TableCompactExpandedRow component.
- `row`: Row. (type `TableTreeRow<TableBaseData, TableUnifiedKey>`; required)
- `index`: Index of the current item. (type `number`; required)
- `colspan`: Colspan. (type `number`; required)

### TableCompactHead

#### Props
Properties for the TableCompactHead component.
- `header`: Engine header instance. (type `import("@tanstack/table-core").Header_Core<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; col...`; required)

### TableCompactRow

#### Props
Properties for the TableCompactRow component.
- `row`: Row. (type `TableTreeRow<TableBaseData, TableUnifiedKey>`; required)
- `index`: Index of the current item. (type `number`; required)
- `leafColumns`: Leaf columns. (type `TableColumn<TableBaseData>[]`; required)

### TableContent

- No documented props, emits, slots, or slot props were available.

### TableDataCell

#### Slot Props
Slot properties for the TableDataCell component.
- `value`: Value associated with the current item. (type `TableRowValue<T> extends any ? K extends `${infer Key}.${infer Rest}` ? Key extends Exclude<keyof T, 'children'> ? Re...`; required)
- `index`: Index of the current item. (type `number`; required)
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `engineColumn`: Engine column instance exposed in the slot scope. (type `TableEngineColumn<T>`; optional)
- `table`: Engine table instance exposed in the slot scope (full TanStack API). (type `TableEngineTable<T>`; optional)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)
- `expanded`: Whether expanded. (type `boolean`; required)
- `toggleExpand`: Toggle expand exposed in the slot scope. (type `() => void`; required)

### TableEmpty

#### Slot Props
Slot properties for the TableEmpty component.
- `columnSize`: Column size exposed in the slot scope. (type `number`; required)

### TableExpand

#### Slot Props
Slot properties for the TableExpand component.
- `ariaLabel`: Aria label exposed in the slot scope. (type `string`; required)
- `index`: Index of the current item. (type `number`; required)
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `engineColumn`: Engine column instance exposed in the slot scope. (type `TableEngineColumn<T>`; optional)
- `table`: Engine table instance exposed in the slot scope (full TanStack API). (type `TableEngineTable<T>`; optional)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)
- `expanded`: Whether expanded. (type `boolean`; required)
- `toggleExpand`: Toggle expand exposed in the slot scope. (type `() => void`; required)

### TableExpandedRow

#### Slot Props
Slot properties for the TableExpandedRow component.
- `index`: Index of the current item. (type `number`; required)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)

### TableFilterPopover

#### Props
Properties for the TableFilterPopover component.
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `{ root: ClassValue; header: ClassValue; content: ClassValue; fixed: ClassValue; footer: ClassValue; cell: ClassValue;...`; required)
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `filterValue`: Filter value exposed in the slot scope. (type `string`; required)
- `filterValues`: Filter values exposed in the slot scope. (type `string[]`; required)
- `filterState`: Filter state exposed in the slot scope. (type `TableFilterValue`; optional)
- `filtered`: Whether filtered. (type `boolean`; required)
- `filterOptions`: Filter options exposed in the slot scope. (type `TableColumnFilterOption[]`; required)
- `setFilterValue`: Set filter value exposed in the slot scope. (type `(value: string) => void`; required)
- `setFilterValues`: Set filter values exposed in the slot scope. (type `(values: string[]) => void`; required)
- `setFilterState`: Set filter state exposed in the slot scope. (type `(value: TableFilterValue | undefined) => void`; required)
- `toggleFilterOption`: Toggle filter option exposed in the slot scope. (type `(value: string) => void`; required)
- `isFilterOptionSelected`: Whether the filter option is selected. (type `(value: string) => boolean`; required)
- `clearFilter`: Clear filter exposed in the slot scope. (type `() => void`; required)

### TableFooter

- No documented props, emits, slots, or slot props were available.

### TableHead

- No documented props, emits, slots, or slot props were available.

### TableHeader

#### Slot Props
Slot properties for the TableHeader component.
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `engineColumn`: Engine column instance exposed in the slot scope. (type `import("@tanstack/table-core").Column_Core<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; col...`; required)
- `table`: Engine table instance exposed in the slot scope (full TanStack API). (type `TableEngineTable<T>`; optional)
- `colSpan`: Col span exposed in the slot scope. (type `number`; required)
- `rowSpan`: Row span exposed in the slot scope. (type `number`; required)
- `sortable`: Whether sortable. (type `boolean`; required)
- `filterable`: Whether filterable. (type `boolean`; required)
- `filtered`: Whether filtered. (type `boolean`; required)
- `resizable`: Whether resizable. (type `boolean`; required)
- `sortOrder`: Sort order exposed in the slot scope. (type `SortDirection`; optional)
- `multiple`: Whether multiple values are supported. (type `boolean`; optional)
- `checked`: Whether the item is checked. (type `CheckedState`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `updateChecked`: Update checked exposed in the slot scope. (type `((value: CheckedState | null) => void)`; optional)
- `toggleSort`: Toggle sort exposed in the slot scope. (type `() => void`; required)
- `filterValue`: Filter value exposed in the slot scope. (type `string`; required)
- `filterValues`: Filter values exposed in the slot scope. (type `string[]`; required)
- `filterState`: Filter state exposed in the slot scope. (type `TableFilterValue`; optional)
- `filterOptions`: Filter options exposed in the slot scope. (type `TableColumnFilterOption[]`; required)
- `setFilterValue`: Set filter value exposed in the slot scope. (type `(value: string) => void`; required)
- `setFilterValues`: Set filter values exposed in the slot scope. (type `(values: string[]) => void`; required)
- `setFilterState`: Set filter state exposed in the slot scope. (type `(value: TableFilterValue | undefined) => void`; required)
- `toggleFilterOption`: Toggle filter option exposed in the slot scope. (type `(value: string) => void`; required)
- `isFilterOptionSelected`: Whether the filter option is selected. (type `(value: string) => boolean`; required)
- `clearFilter`: Clear filter exposed in the slot scope. (type `() => void`; required)

### TableHeaderFilter

#### Slot Props
Slot properties for the TableHeaderFilter component.
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `filterValue`: Filter value exposed in the slot scope. (type `string`; required)
- `filterValues`: Filter values exposed in the slot scope. (type `string[]`; required)
- `filterState`: Filter state exposed in the slot scope. (type `TableFilterValue`; optional)
- `filtered`: Whether filtered. (type `boolean`; required)
- `filterOptions`: Filter options exposed in the slot scope. (type `TableColumnFilterOption[]`; required)
- `setFilterValue`: Set filter value exposed in the slot scope. (type `(value: string) => void`; required)
- `setFilterValues`: Set filter values exposed in the slot scope. (type `(values: string[]) => void`; required)
- `setFilterState`: Set filter state exposed in the slot scope. (type `(value: TableFilterValue | undefined) => void`; required)
- `toggleFilterOption`: Toggle filter option exposed in the slot scope. (type `(value: string) => void`; required)
- `isFilterOptionSelected`: Whether the filter option is selected. (type `(value: string) => boolean`; required)
- `clearFilter`: Clear filter exposed in the slot scope. (type `() => void`; required)

### TableHeaderResize

#### Slot Props
Slot properties for the TableHeaderResize component.
- `column`: Column exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `resizing`: Whether resizing. (type `boolean`; required)
- `ariaLabel`: Aria label exposed in the slot scope. (type `string`; required)
- `onPointerdown`: Callback invoked when the pointerdown event fires. (type `(event: PointerEvent) => void`; required)
- `onKeydown`: Callback invoked when the keydown event fires. (type `(event: KeyboardEvent) => void`; required)

### TableHeaderSelection

#### Slot Props
Slot properties for the TableHeaderSelection component.
- `column`: Column exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `multiple`: Whether multiple values are supported. (type `boolean`; required)
- `checked`: Whether the item is checked. (type `boolean | 'indeterminate'`; required)
- `disabled`: Whether the component is disabled. (type `boolean`; required)
- `ariaLabel`: Accessible label for the "select all" control. (type `string`; required)
- `updateChecked`: Update checked exposed in the slot scope. (type `(value: CheckedState | null) => void`; required)

### TableHeaderSort

#### Slot Props
Slot properties for the TableHeaderSort component.
- `ariaLabel`: Aria label exposed in the slot scope. (type `string`; required)
- `column`: Column exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `sortOrder`: Sort order exposed in the slot scope. (type `SortDirection`; optional)
- `toggleSort`: Toggle sort exposed in the slot scope. (type `() => void`; required)

### TableIndex

#### Slot Props
Slot properties for the TableIndex component.
- `index`: Index of the current item. (type `number`; required)
- `column`: Column exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)

### TableRadio

#### Props
Properties for the TableRadio component.
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `checked`: Whether the item is checked. (type `boolean`; optional)

### TableRoot

#### Props
Properties for the TableRoot component.
- `dir`: Reading direction of the component. (type `Direction`; optional)

### TableRow

- No documented props, emits, slots, or slot props were available.

### TableScroll

- No documented props, emits, slots, or slot props were available.

### TableSelection

#### Props
Properties for the TableSelection component.
- `defaultSelected`: Default selected. (type `(M extends true ? R[] : R)`; optional)
- `selected`: Whether the item is selected. (type `(M extends true ? R[] : R)`; optional)
- `multiple`: Whether multiple values are supported. (type `M`; optional)
#### Slot Props
Slot properties for the TableSelection component.
- `multiple`: Whether multiple values are supported. (type `boolean`; required)
- `checked`: Whether the item is checked. (type `boolean`; required)
- `ariaLabel`: Aria label exposed in the slot scope. (type `string`; required)
- `toggleSelect`: Toggle select exposed in the slot scope. (type `() => void`; required)
- `index`: Index of the current item. (type `number`; required)
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `engineColumn`: Engine column instance exposed in the slot scope. (type `TableEngineColumn<T>`; optional)
- `table`: Engine table instance exposed in the slot scope (full TanStack API). (type `TableEngineTable<T>`; optional)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)
- `expanded`: Whether expanded. (type `boolean`; required)
- `toggleExpand`: Toggle expand exposed in the slot scope. (type `() => void`; required)

### TableTreeToggle

#### Slot Props
Slot properties for the TableTreeToggle component.
- `ariaLabel`: Aria label exposed in the slot scope. (type `string`; required)
- `index`: Index of the current item. (type `number`; required)
- `column`: Column definition exposed in the slot scope. (type `(ColumnDef<{ columnFilteringFeature: import("@tanstack/table-core").TableFeature; columnGroupingFeature: import("@tan...`; required)
- `engineColumn`: Engine column instance exposed in the slot scope. (type `TableEngineColumn<T>`; optional)
- `table`: Engine table instance exposed in the slot scope (full TanStack API). (type `TableEngineTable<T>`; optional)
- `row`: Row exposed in the slot scope. (type `T`; required)
- `level`: Level exposed in the slot scope. (type `number`; required)
- `hasChildren`: Whether the component has children. (type `boolean`; required)
- `expanded`: Whether expanded. (type `boolean`; required)
- `toggleExpand`: Toggle expand exposed in the slot scope. (type `() => void`; required)

### TableVirtualSpacerRow

#### Props
Properties for the TableVirtualSpacerRow component.
- `isVirtual`: Whether virtual scrolling is enabled. (type `boolean`; required)
- `colspan`: Number of columns the spacer spans. (type `number`; required)
- `paddingStart`: Padding applied before the start of the row. (type `number`; required)
- `paddingEnd`: Padding applied after the end of the row. (type `number`; required)

## Notes

### Architecture and benchmark differences

The table engine is [`@tanstack/vue-table`](https://tanstack.com/table) (v9): column defs, sorting, filtering, expanding, pinning, and sizing follow TanStack state contracts (`SortingState`, `ColumnFiltersState`, `ExpandedState`, `ColumnPinningState`, `ColumnSizingState`), and all of them are controlled/uncontrolled dual channels via `useControllableState` + `useSelection`; all base primitives stay zero-style and only the UI wrapper injects `tableVariants` classes. The filter popover and single-select radio are UI-internal components consumed by default slots, but consumers can replace them entirely via same-name slots (`header-filter`/`selection`, etc.). Sort buttons and filter triggers are absolutely-positioned icon buttons with localized `aria-label`s; column resizing supports both pointer (`PointerEvent`) and keyboard (arrow-key) channels. Virtualization uses the built-in `@soybeanjs/headless` virtualizer, rendering only visible rows while syncing measured column widths. Ant Design / Element Plus tables are declarative component instances (`el-table-column`) whose fixed columns rely on config classes; SoybeanUI's controlled state, `aria-sort` semantics, and full-chain localization (including the filter popover) exceed most mainstream libraries.

| Capability                            | SoybeanUI | Ant Design | Element Plus | Naive UI | Mantine Table |
| :------------------------------------ | :-------: | :--------: | :----------: | :------: | :-----------: |
| headless/styled split                 |    ✅     |     —      |      —       |    —     |       —       |
| Config columns + grouped headers      |    ✅     |     ✅     |      ✅      |    ✅    |      ✅       |
| Sorting (aria-sort + controlled)      |    ✅     |     ✅     |      ✅      |    ✅    |      ⚠️       |
| Filtering (keyword + multi-select)    |    ✅     |     ✅     |      ✅      |    ✅    |      ⚠️       |
| Selection (multi/single + select-all) |    ✅     |     ✅     |      ✅      |    ✅    |      ⚠️       |
| Expandable + tree rows                |    ✅     |     ✅     |      ✅      |    ✅    |      ⚠️       |
| Fixed columns / fixed header          |    ✅     |     ✅     |      ✅      |    ✅    |      ⚠️       |
| Drag + keyboard column resize         |    ✅     |     ✅     |      ⚠️      |    ✅    |       —       |
| Virtualization                        |    ✅     |     ✅     |      ⚠️      |    ✅    |      ⚠️       |

`⚠️` = partial support (Mantine Table's sorting/filtering/selection are manual; Element Plus virtualization only exists in the separate `el-table-v2`; Element Plus drag-resize requires `border` mode).

### Cautions

- Columns are TanStack `ColumnDef`s first: data columns use `accessorKey` (or `accessorFn`), `header` for the label, `size`/`minSize` for pixel widths. The legacy `dataIndex`/`title` fields have been removed — rename them to `accessorKey`/`header`.
- Sorting, filtering, and resizing are opt-in per column: `enableSorting`, `enableColumnFilter`, `resizable` (all default `false`).
- Group columns nest via `columns` (TanStack shape); tree rows nest via the row `children` field or `getChildren` — these are different concepts and different fields.
- `multiple` defaults to `true` (multi-select); setting it to `false` renders row radios, makes `selected` a single value (`R | undefined`), and hides the header select-all checkbox.
- Sorting/filtering/expansion/pinning/sizing are all **controlled/uncontrolled dual channels**: when passing `sorting` (etc.) you must also listen for the matching `update:sorting` (or use `v-model:sorting`) to write back, otherwise state does not update.
- The controlled `expanded` state is a TanStack `ExpandedState` keyed by `String(rowKey(row))` (`{ '1': true }`, or `true` for all); `defaultExpandAll` only applies when expansion is uncontrolled.
- While a column filter is active, tree rows are force-expanded so filtered ancestors stay visible.
- Virtualization requires `height`; without it `virtual` is ignored (falls back to normal rendering).
- Fixed columns inject a background on `data-fixed` cells; fixed-column shadows are drawn via the `data-fixed-last-start`/`data-fixed-first-end` data attributes — keep these attributes when customizing `cell`/`row` slots to preserve the visuals.
- Filter popover copy (summary, keyword, options, clear) and the empty state follow the `ConfigProvider` locale; the column label falls back through `header` → `id`/`accessorKey`.

## FAQ

### How do I select rows and read the selected data?

Use `multiple` (multi-select by default) with `v-model:selected` and `rowKey`:

```vue
<STable :columns="columns" :data="data" :row-key="row => row.id" v-model:selected="selected" />
```

`selected` is an array of the selected rows' `rowKey`s; map them back to `data` when you need the full row objects.

### How do I make a single-select table?

Set `multiple={false}` — row radios render and `selected` becomes a single value:

```vue
<STable :columns="columns" :data="data" :row-key="row => row.id" :multiple="false" v-model:selected="selected" />
```

### How do I customize the filter popover?

Replace the default `STableFilterPopover` entirely with the `header-filter` slot, or configure `filter` options and keyword matching on the column:

```vue
<STable :columns="columns" :data="data" :row-key="row => row.id">
  <template #header-filter="{ column, filtered, filterValues, setFilterValues, clearFilter }">
    
  </template>

```

### How do I set the initial sort/filter state?

Seed the uncontrolled `defaultSorting`/`defaultColumnFilters`, then let the component maintain state internally; switch to the controlled channels and listen for `update:sorting`/`update:columnFilters` when you need external sync:

```vue
<STable :columns="columns" :data="data" :row-key="row => row.id" :default-sorting="[{ id: 'age', desc: false }]" />
```

### How do I handle large datasets?

Enable virtualization (`virtual` + `height`) and tune `estimateSize` as needed; the engine row models are memoized, so 1000-row workloads need no extra handling.

### How do I render a summary/footer row?

Use the `footer` slot — it receives `columnSize`, letting you render summary cells per column:

```vue
<STable :columns="columns" :data="data" :row-key="row => row.id">
  <template #footer="{ columnSize }">
    <STableRow>
      <STableCell :colspan="columnSize">Total: {{ data.length }} items</STableCell>
    </STableRow>
  </template>

```

### How do I localize table copy?

The empty state and all interaction `aria-label`s (sort/filter/select/expand/resize) follow the `ConfigProvider` `locale` (`table.*` messages, 14 language packs); override per instance via `ConfigProvider` `messages`, or use the same-name slots for fully custom content.

## Engine escape hatch

`STable` is a component-driven wrapper, but the TanStack engine is never locked away — four graded escape hatches:

1. **Slot props** — every header/data-cell slot receives `table` (the engine table instance) and `engineColumn` (the engine column instance) alongside `column`/`row`/`value`:

```vue
<STable :columns="columns" :data="data" :row-key="row => row.id">
  <template #age="{ value, table }">
    {{ value }} ({{ table.getPreFilteredRowModel().flatRows.length }} rows total)
  </template>

```

2. **`useTableEngine()`** — inject the engine from any component rendered inside the table subtree (deep custom cells, toolbar widgets):

```ts
import { useTableEngine } from '@soybeanjs/headless/table';

const table = useTableEngine();

table.value.setGrouping([{ id: 'city' }]);
```

3. **Template ref** — the engine instance is the exposed root, so control the table directly from outside:

```ts
const tableRef = useTemplateRef<TableEngineTable>('tableRef');

tableRef.value.previousPage();
```

4. **`tableOptions` prop** — pass raw TanStack table options through for everything the component does not wire explicitly (pagination, row selection models, manual server modes, `meta`, `initialState`, faceted values...). Keys the component owns (state wiring, change handlers) take precedence:

```vue
<STable
  :columns="columns"
  :data="data"
  :row-key="row => row.id"
  :table-options="{
    enableRowSelection: true,
    getFilteredSelectedRowModel: createFilteredSelectedRowModel()
  }"
/>
```

Cell customization priority: named slot > `columnDef.cell` render function (TanStack-native, rendered via `FlexRender`) > plain value text. Headers follow the same chain with `columnDef.header`.

## Migration from v0.4x

v0.50.0 replaces the hand-rolled column model with [`@tanstack/vue-table`](https://tanstack.com/table). TanStack naming is the first citizen and legacy fields get no aliases (`dataIndex` / `sortState` and friends must be renamed by hand); the most frequent legacy fields map as follows:

| v0.4x (legacy)                            | v0.50.0 (TanStack-first)                                           |
| :---------------------------------------- | :----------------------------------------------------------------- |
| `{ title, dataIndex }`                    | `{ header, accessorKey }` (`dataIndex` alias removed)              |
| `sorter: true` / `sorter(a, b)`           | `enableSorting: true` / `sortFn: (rowA, rowB) => number`           |
| `filter: true` / `filter: { ... }`        | `enableColumnFilter: true` / `filterPlaceholder` / `filterOptions` |
| `width: '140px'` / `minWidth`             | `size: 140` / `minSize` (px numbers)                               |
| group column `{ key, children }`          | `{ id, columns }` (TanStack group shape)                           |
| `sortState` / `defaultSortState`          | `sorting` / `defaultSorting` (`SortingState`) — alias removed      |
| `filterState` / `defaultFilterState`      | `columnFilters` / `defaultColumnFilters` (`ColumnFiltersState`)    |
| `columnWidths` / `defaultColumnWidths`    | `columnSizing` / `defaultColumnSizing` (`Record<string, number>`)  |
| `expanded: R[]`                           | `expanded: ExpandedState` (`{ '1': true }` or `true`)              |
| `update:sortState` / `update:filterState` | `update:sorting` / `update:columnFilters`                          |

### Before / after

```vue

<script setup>
const columns = [
  { title: 'Name', dataIndex: 'name', sorter: true, width: '180px' },
  { title: 'Age', dataIndex: 'age', align: 'center', filter: true }
];
const expanded = ref([1]);
</script>

<script setup>
const columns = [
  { header: 'Name', accessorKey: 'name', enableSorting: true, size: 180 },
  { header: 'Age', accessorKey: 'age', align: 'center', enableColumnFilter: true }
];
const expanded = ref({ 1: true });
</script>
```

## Tabs

- Page URL: /components/tabs
- Markdown URL: /components/tabs.md
- Description: A set of layered sections of content—known as tab panels—that are displayed one at a time.

# Tabs

## Overview

A set of layered sections of content—known as tab panels—that are displayed one at a time.

## Features

- **WAI-ARIA tabs pattern** — the list renders as a `tablist`, triggers as `role="tab"`, panels as `role="tabpanel"`; the active tab carries `aria-selected`, each trigger links its panel via `aria-controls`/`aria-labelledby`, and `aria-orientation` reflects the layout direction.
- **Data-driven compact composition** — `STabs` delegates item iteration, default trigger/content composition, and indicator rendering to the generic headless `TabsCompact<T>`, which owns the ARIA wiring for every item.
- **Controlled or uncontrolled state** — `modelValue` supports `v-model` (controlled); `defaultValue` provides uncontrolled usage backed by `useControllableState`.
- **Two activation modes** — `activationMode: 'automatic'` activates a tab on focus (ARIA default); `'manual'` activates only on click / `Enter` / `Space`.
- **Full keyboard navigation** — the `useRovingFocusGroup` hook provides arrow-key (and Home/End) movement that skips disabled tabs; `Enter` / `Space` activates the focused tab.
- **Presence-based content mounting** — `unmountOnHide: true` (default) unmounts inactive panels after the exit animation; `false` keeps every panel mounted but `hidden`; `forceMount` keeps a panel in the DOM unconditionally.
- **Animated indicator** — a sliding indicator tracks the active tab with CSS variables (`--soybean-tabs-indicator-size` / `--soybean-tabs-indicator-position`), measured via `ResizeObserver` and re-positioned on value/direction changes; RTL offsets are mirrored automatically.
- **Horizontal and vertical layouts** — `orientation: 'vertical'` stacks the list and runs the indicator along the block axis.
- **Three customization slots** — `trigger` (scoped `{ ...item, active }`), `content` (scoped `{ ...item, active }`), and `indicator`.
- **Six visual variants** — `size` (xs…2xl), `orientation` (horizontal / vertical), `shape` (square / rounded), `fill` (full / auto), and `enableIndicator` (falls back to a solid active-trigger style) via the `tabsVariants` `scv()` recipe.
- **Headless composition** — `TabsRoot` / `TabsList` / `TabsTrigger` / `TabsContent` / `TabsIndicator` / `TabsCompact` are exported from `@soybeanjs/headless/tabs` for fully custom styled builds.

## Usage

Usage examples for tabs are rendered on the site.

> `STabs` now delegates item iteration, default trigger/content composition, and indicator rendering to headless `TabsCompact`. For unstyled, data-driven usage, import `TabsCompact` from `@soybeanjs/headless/tabs`.

## Demos

Interactive demos for tabs are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): Tabs, TabsCompact, TabsContent, TabsIndicator, TabsList, TabsRoot, TabsTrigger.

### Tabs

#### Props
Properties for the Tabs component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Styled tabs ui slots, including `indicatorContent` for the compact indicator body. (type `Partial<TabsUi>`; optional)
- `fill`: Fill. (type `TabsFill`; optional)
- `shape`: Shape of the component. (type `TabsShape`; optional)
- `items`: Items rendered by the component. (type `T[]`; required)
- `enableIndicator`: Whether to enable indicator. (type `boolean`; optional)
- `listProps`: Properties forwarded to the list element. (type `TabsListProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `TabsTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `TabsContentProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `TabsIndicatorProps`; optional)
- `modelValue`: The controlled value of the tab to activate. Can be bind as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs (type `T['value'] | null`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
#### Emits
Events for the Tabs component.
- `update:modelValue`: Event handler called when the value changes (type `[payload: Exclude<T, undefined>]`; parameters `payload: Exclude<T, undefined>`)
#### Slots
Slots for the Tabs component.
- `trigger`: Custom content for the trigger slot. (type `((props: T & { selected: boolean; }) => any) | undefined`)
- `content`: Custom content for the content slot. (type `((props: T & { selected: boolean; }) => any) | undefined`)
- `indicator`: Custom content for the indicator slot. (type `(() => any) | undefined`)

### TabsCompact

#### Props
Properties for the TabsCompact component.
- `items`: Items rendered by the component. (type `T[]`; required)
- `enableIndicator`: Whether to enable indicator. (type `boolean`; optional)
- `listProps`: Properties forwarded to the list element. (type `TabsListProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `TabsTriggerProps`; optional)
- `contentProps`: Properties forwarded to the content element. (type `TabsContentProps`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `TabsIndicatorProps`; optional)
- `modelValue`: The controlled value of the tab to activate. Can be bind as `v-model`. (type `T['value'] | null`; optional)
- `defaultValue`: The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs (type `T['value'] | null`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
#### Emits
Events for the TabsCompact component.
- `update:modelValue`: Event handler called when the value changes (type `[payload: Exclude<T, undefined>]`; parameters `payload: Exclude<T, undefined>`)
#### Slots
Slots for the TabsCompact component.
- `trigger`: Custom content for the trigger slot. (type `((props: T & { selected: boolean; }) => any) | undefined`)
- `content`: Custom content for the content slot. (type `((props: T & { selected: boolean; }) => any) | undefined`)
- `indicator`: Custom content for the indicator slot. (type `(() => any) | undefined`)

### TabsContent

#### Props
Properties for the TabsContent component.
- `value`: A unique value that associates the content with a trigger. (type `string | number`; required)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)

### TabsIndicator

#### Props
Properties for the TabsIndicator component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TabsList

- No documented props, emits, slots, or slot props were available.

### TabsRoot

#### Props
Properties for the TabsRoot component.
- `modelValue`: The controlled value of the tab to activate. Can be bind as `v-model`. (type `T`; optional)
- `defaultValue`: The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs (type `T`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
#### Emits
Events for the TabsRoot component.
- `update:modelValue`: Event handler called when the value changes (type `[payload: Exclude<T, undefined>]`; parameters `payload: Exclude<T, undefined>`)

### TabsTrigger

#### Props
Properties for the TabsTrigger component.
- `value`: A unique value that associates the trigger with a content. (type `string | number`; required)
- `disabled`: When `true`, prevents the user from interacting with the tab. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark comparison

| Concern                           | SoybeanUI                                          | shadcn-vue / Radix `Tabs`           | Ant Design `Tabs`                   | Element Plus `Tabs`   |
| :-------------------------------- | :------------------------------------------------- | :---------------------------------- | :---------------------------------- | :-------------------- |
| Headless / styled separation      | ✅ `@soybeanjs/headless/tabs` + `scv()`            | ✅ headless primitives              | ❌ single package                   | ❌ single package     |
| Data-driven compact API           | ✅ generic `TabsCompact<T>` + `items`              | ✅ `TabList`/`Tab`/`TabPanel` parts | ✅ config-driven (items)            | ✅ config-driven      |
| Controlled / uncontrolled         | ✅ `modelValue` / `defaultValue`                   | ✅ `modelValue` / `defaultValue`    | ✅ `activeKey` / `defaultActiveKey` | ✅ `v-model`          |
| Activation mode                   | ✅ `automatic` / `manual`                          | ✅                                  | ❌ (always automatic)               | ❌ (always automatic) |
| Keyboard navigation               | ✅ roving focus (arrows/Home/End) + Enter/Space    | ✅ roving focus                     | ✅ arrows / Home / End              | ✅ arrows             |
| Disabled tab skipping             | ✅ roving focus skips disabled items               | ✅                                  | ✅                                  | ✅                    |
| Presence / forceMount content     | ✅ `unmountOnHide` + `forceMount` + exit animation | ✅ `forceMount`                     | ❌                                  | ❌                    |
| Animated indicator                | ✅ CSS vars + ResizeObserver + RTL mirroring       | ❌ (no built-in indicator)          | ✅ ink bar (line type)              | ❌                    |
| Horizontal + vertical             | ✅ `orientation`                                   | ✅                                  | ✅ `tabPosition`                    | ✅ `tab-position`     |
| Variants                          | ✅ size × orientation × shape × fill               | ❌ (style your own)                 | ✅ type / size / tabBarGutter       | ✅ type / size        |
| Custom slots                      | ✅ `trigger` / `content` / `indicator`             | ✅ part-level                       | ✅ `label` / `children`             | ✅ `label` / `icon`   |
| ARIA wiring (controls/labelledby) | ✅ automatic per item                              | ✅ automatic                        | ✅                                  | ✅                    |

### Runtime considerations

1. **Activation on focus** — with `activationMode: 'automatic'` (default), focusing a tab via keyboard (or `ArrowRight`/`ArrowLeft`) activates it; with `'manual'` only clicking or pressing `Enter`/`Space` activates.
2. **Indicator measurement** — the indicator positions itself against the active trigger after the list ref is attached, on value/direction changes, and on resize; it renders only after the first successful measurement.
3. **RTL positioning** — in `dir: 'rtl'` the indicator offset is mirrored (`list.clientWidth - offsetLeft - offsetWidth`) and the CSS `rtl:-translate-x-…` flips the translation, so the indicator stays anchored to the active tab.
4. **Content presence** — with `unmountOnHide: true`, inactive panel content is removed after the exit animation; with `false` it stays mounted but carries the `hidden` attribute; `forceMount` keeps the panel in the DOM while still honoring `hidden` for inactive panels.
5. **Controlled vs. uncontrolled** — when `modelValue` is provided, internal writes only emit `update:modelValue`; the DOM follows the prop, so external changes re-render automatically.
6. **Disabled tabs** — a disabled trigger keeps focusability only for roving focus (`data-disabled`, not the native `disabled` attribute), so arrow navigation can skip it; `mousedown` and key activation are blocked.
7. **ARIA ids** — triggers and panels are linked with deterministic ids (`soybean-tabs-trigger-{value}` / `soybean-tabs-content-{value}`); `aria-controls` is only emitted once the matching panel registers itself.

## FAQ

### How do I switch from automatic to manual activation?

Set `activationMode="manual"`. In manual mode focusing a tab no longer activates it; users activate a tab by clicking or pressing `Enter`/`Space`. This follows the WAI-ARIA tabs pattern for panels that are slow to render.

### Why doesn't the indicator appear immediately?

The indicator needs a first measurement of the active trigger (offset + size). It renders right after the list element is attached or the value changes. In a real browser a `ResizeObserver` notification also triggers a re-measure, keeping it aligned on resize.

### What does `unmountOnHide` control?

With `true` (default), switching tabs removes inactive panel content from the DOM after the exit animation — best for performance. With `false`, every panel stays mounted but inactive ones are `hidden` — best for preserving state (scroll positions, form inputs).

### How is keyboard navigation handled?

The list is a roving-focus group: `ArrowLeft`/`ArrowRight` (or `ArrowUp`/`ArrowDown` in vertical mode) move focus, `Home`/`End` jump to the first/last tab, disabled tabs are skipped, and `Enter`/`Space` activates the focused tab.

### Can I fully customize the tab rendering?

Yes — the `trigger` slot receives scoped `{ ...item, active }` props, the `content` slot `{ ...item, active }`, and `indicator` replaces the indicator body. For a completely custom structure, compose `TabsRoot` / `TabsList` / `TabsTrigger` / `TabsContent` / `TabsIndicator` from `@soybeanjs/headless/tabs` and inject styles via `provideTabsUi` (or `STabs`'s `ui` prop).

### Do I need to wire `aria-controls` myself?

No. Each trigger automatically points `aria-controls` at its panel id (`soybean-tabs-content-{value}`) once the panel mounts, and each panel sets `aria-labelledby` back to its trigger — both stay in sync when items are added or removed.

## Tag

- Page URL: /components/tag
- Markdown URL: /components/tag.md
- Description: A compact label used to categorize, filter, or mark content inline. STag combines the headless Tag primitive (zero styles) with the tagVariants style recipe (8 colors × 6 sizes × 5 variants × 2 shapes) and exposes leading/trailing/close slots.

# Tag

## Overview

A compact label used to categorize, filter, or mark content inline. `STag` combines the headless `Tag` primitive (zero styles) with the `tagVariants` style recipe (8 colors × 6 sizes × 5 variants × 2 shapes) and exposes `leading`/`trailing`/`close` slots.

Use it for status labels, category chips, keywords, or filterable metadata. Prefer `badge` when the label should overlay a host element as a count/notification bubble, and `alert` for larger contextual feedback.

`STag` supports `v-model:open` for controlled visibility and a `closable` close button with a localized accessible label. The headless `Tag` primitive exposes the `close` action via slot props for fully custom compositions.

## Usage

Usage examples for tag are rendered on the site.

## Features

- 🧩 Headless/styled split — the headless `Tag` owns the `open`/`close` state; `STag` injects the `tagVariants` classes and the default close control
- 🎨 8 colors — `ThemeColor` values (`primary`/`destructive`/`success`/`warning`/`info`/`carbon`/`secondary`/`accent`)
- 🖌️ 5 variants — `solid`/`pure`/`outline`/`soft`/`ghost`/`raw` covering filled, bordered, and tinted looks
- 📐 6 sizes — xs–2xl from `ThemeSize`
- 🟦 2 shapes — `auto` (rounded) and `rounded` (pill)
- ❌ Closable — `closable` renders a close button driven by `v-model:open`; the close control is a real `<button>` with a localized `aria-label` (keyboard-operable)
- 🌐 RTL-ready — layout uses inline-flex and logical spacing
- ♿ Accessible by default — the close button is focusable, exposes an accessible name, and `axe-core` reports zero violations in the default and closable states

## Component family

- `STag` (styled) — the entry wrapper; `tagVariants` recipe plus `leading`/`trailing`/`close` slots
- `Tag` (headless) — the state primitive; owns `open` via `useControllableState` and exposes the `close` action through slot props

## Demos

Interactive demos for tag are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Tag.

### Tag

#### Props
Properties for the Tag component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `TagVariant`; optional)
- `shape`: Shape of the component. (type `TagShape`; optional)
- `content`: Content. (type `string`; optional)
- `closable`: Whether the component can be closed. (type `boolean`; optional)
- `open`: Whether the component is open. Controlled when provided. (type `boolean`; optional)
#### Emits
Events for the Tag component.
- `update:open`: Emitted when the open state changes. (type `[open: boolean]`; parameters `open: boolean`)

## Notes

### Architecture and benchmark differences

The headless `Tag` is a minimal present/close state primitive, and `STag` keeps all styling in the `tagVariants` recipe while providing the default close control. This mirrors shadcn/ui's headless/styled split, unlike Ant Design, Element Plus, Mantine and Naive UI which ship a single styled tag with `closable`/`onClose` props. SoybeanUI's close button is a real focusable `<button>` whose `aria-label` is localized from `tag.remove` (e.g. `Remove {label}`), whereas several libraries rely on a plain `×` glyph that is less robust for screen readers.

| Capability                     | SoybeanUI | shadcn/ui | Ant Design Tag | Element Plus Tag | Mantine Badge | Naive UI Tag |
| :----------------------------- | :-------: | :-------: | :------------: | :--------------: | :-----------: | :----------: |
| Headless/styled split          |    ✅     |    ✅     |       —        |        —         |       —       |      —       |
| Color variants (8)             |    ✅     |    ✅     |       ✅       |        ✅        |      ✅       |      ✅      |
| Variants (solid/outline/soft)  |    ✅     |    ✅     |       ✅       |        ✅        |      ✅       |      ✅      |
| Size variants (6)              |    ✅     |     —     |       ✅       |        ✅        |      ✅       |      ✅      |
| Shape (auto / pill)            |    ✅     |    ✅     |       ✅       |        ✅        |      ✅       |      ✅      |
| Closable tag                   |    ✅     |     —     |       ✅       |        ✅        |       —       |      ✅      |
| Localized close `aria-label`   |    ✅     |     —     |       —        |        ✅        |       —       |      —       |
| Controlled visibility (`open`) |    ✅     |     —     |       —        |        —         |       —       |      —       |
| RTL-ready                      |    ✅     |    ✅     |       ✅       |        —         |       —       |      ✅      |

`—` = unsupported or a different interaction model.

### Cautions

- The close button's `aria-label` is derived from the localized `tag.remove` template using the `content` prop. If you pass the label via the `default` slot instead of `content`, the default close `aria-label` falls back to the bare verb — override it through the `close` slot or the `content` prop.
- `open` defaults to `true`. Use `:open="false"` or `v-model:open` to control visibility.
- `variant="pure"`/`outline` intentionally override the color foreground to use `foreground`/`border` tokens; `soft`/`ghost` tint the background with a translucent color.
- The close button inherits the tag's text color and uses transparent background/border; on a `soft` background it stays visible, but verify contrast for your chosen color/background combination.
- The tag root is a `<div>` — if you need the whole tag clickable, wrap it in a link/button yourself.

### Roadmap

No blocking gaps identified for the core tag API. A dedicated standalone `tag-group` and `checkable` tag behavior are evaluated enhancements tracked in `docs/roadmap.md`.

## FAQ

### How do I make a closable tag?

Set `closable` and bind `open` with `v-model`:

```vue

```

### How do I react when the tag is closed?

Listen to `@update:open` — it emits `false` when the close button is activated:

```vue

```

### How do I change the variant, shape and color?

Use `variant` (`solid`/`pure`/`outline`/`soft`/`ghost`/`raw`), `shape` (`auto`/`rounded`) and `color`:

```vue

```

### How do I add an icon before or after the text?

Use the `leading` / `trailing` slots:

```vue

  <template #leading><SIcon icon="lucide:circle" /></template>

```

### How do I customize the close button?

Use the `close` slot and read the `close` action from its props:

```vue

  <template #close="{ close }">
    <button type="button" aria-label="Dismiss" @click="close">×</button>
  </template>

```

## Tags Input

- Page URL: /components/tags-input
- Markdown URL: /components/tags-input.md
- Description: A composable multi-value input for adding, displaying, and removing tags. Supports controlled/uncontrolled string[] values, tag creation via Enter/Tab/blur/delimiter typing/paste, full keyboard selection and removal (with RTL reversal), max/duplicate constraints, and hidden form-input serialization. Use it for keyword lists, email recipients, or any small-token collection that needs fast keyboard workflows instead of a plain text input.

# Tags Input

## Overview

A composable multi-value input for adding, displaying, and removing tags. Supports controlled/uncontrolled `string[]` values, tag creation via `Enter`/`Tab`/blur/delimiter typing/paste, full keyboard selection and removal (with RTL reversal), `max`/`duplicate` constraints, and hidden form-input serialization. Use it for keyword lists, email recipients, or any small-token collection that needs fast keyboard workflows instead of a plain text input.

## Usage

Usage examples for tags-input are rendered on the site.

## Features

- 🏷 Tag model — controlled/uncontrolled `string[]` via `useControllableState`; add/remove/clear events plus per-action `addTag`/`removeTag` emits
- ⌨️ Full keyboard support — `ArrowLeft`/`ArrowRight` select the adjacent tag (logical direction, reversed in RTL), `Backspace`/`Delete` remove the selected tag, `Home`/`End` jump to the first/last tag, typing deselects
- ✂️ Delimiter & paste — commit the typed value when a delimiter (string or `RegExp`) is entered, or split pasted text (`addOnPaste`)
- ⏎ Commit triggers — `Enter` always commits; `Tab` and blur commit only with `addOnTab`/`addOnBlur`
- 🚦 Constraints — `max` caps the total count, `duplicate` allows repeated values, `displayValue` rewrites the label; rejected values emit `invalid`
- 🧩 Composable parts — `Root`/`Control`/`Item`/`ItemText`/`ItemDelete`/`Clear` with `*Props` passthrough on the compact and a fully replaceable `item` slot
- 📋 Form integration — `name`/`required`/`disabled` serialize through a visually hidden input; `aria-controls` links the input to the tag list container
- 🔤 Localized UI — default `aria-label`s come from locale messages and can be overridden per part
- 🚫 Disabled / readonly — `disabled` blocks all interaction; `readonly` blocks typing but keeps tag removal and clearing available

## Component family

- `STagsInput` — the styled wrapper that forwards props to the headless compact and injects `tagsInputVariants` classes (6 slots: root/item/itemText/itemDelete/control/clear)
- `TagsInputCompact` (headless) — data-driven composition of `TagsInputRoot` + one `TagsInputItem` per value (default item text/delete) + `Control` + `Clear` (gated by `clearable`); import from `@soybeanjs/headless/tags-input` for unstyled usage
- `TagsInputRoot` (headless) — state owner: `useControllableState` for the value array, collection registration, keydown/removal/clear logic, and the visually hidden form input
- `TagsInputControl` (headless) — the committed input: delimiter typing, paste splitting, `Enter`/`Tab`/blur commit, composition guard
- `TagsInputItem` / `TagsInputItemText` / `TagsInputItemDelete` (headless) — a registered collection item with its label span and keyboard-reachable delete button
- `TagsInputClear` (headless) — the clear-all button, hidden until the root has a value (styling) and gated by `clearable` (rendering)

## Demos

Interactive demos for tags-input are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (8): TagsInput, TagsInputClear, TagsInputCompact, TagsInputControl, TagsInputItem, TagsInputItemDelete, TagsInputItemText, TagsInputRoot.

### TagsInput

#### Props
Properties for the TagsInput component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TagsInputUi>`; optional)
- `clearable`: Whether to render the clear trigger. (type `boolean`; optional)
- `controlProps`: Props forwarded to the input element. (type `TagsInputControlProps`; optional)
- `clearProps`: Props forwarded to the clear element. (type `TagsInputClearProps`; optional)
- `itemProps`: Props forwarded to the item element. (type `TagsInputItemProps`; optional)
- `itemTextProps`: Props forwarded to the item text element. (type `TagsInputItemTextProps`; optional)
- `itemDeleteProps`: Props forwarded to the item delete element. (type `TagsInputItemDeleteProps`; optional)
- `dir`: The reading direction of the tags input. (type `Direction`; optional)
- `modelValue`: The controlled value of the tags input. (type `string[]`; optional)
- `defaultValue`: The uncontrolled default value of the tags input. (type `string[]`; optional)
- `addOnPaste`: Whether to add tags on paste. (type `boolean`; optional)
- `addOnTab`: Whether to add tags on tab. (type `boolean`; optional)
- `addOnBlur`: Whether to add tags on blur. (type `boolean`; optional)
- `duplicate`: Whether to allow duplicated tags. (type `boolean`; optional)
- `delimiter`: The delimiter used to add tags. (type `string | RegExp`; optional)
- `max`: Maximum number of tags. Set to 0 for unlimited. (type `number`; optional)
- `displayValue`: Display the value of the tag. Useful when you want to apply modifications to the value like adding a suffix (type `((value: string) => string)`; default `"(value: string) => value"`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the TagsInput component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string[]]`; parameters `value: string[]`)
- `invalid`: Emitted when invalid occurs. (type `[value: string]`; parameters `value: string`)
- `addTag`: Emitted when add tag occurs. (type `[value: string]`; parameters `value: string`)
- `removeTag`: Emitted when remove tag occurs. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the TagsInput component.
- `item`: Custom item content or full item replacement. (type `((props: TagsInputCompactSlotProps) => any) | undefined`)

### TagsInputClear

#### Props
Properties for the TagsInputClear component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TagsInputCompact

#### Props
Properties for the TagsInputCompact component.
- `clearable`: Whether to render the clear trigger. (type `boolean`; optional)
- `controlProps`: Props forwarded to the input element. (type `TagsInputControlProps`; optional)
- `clearProps`: Props forwarded to the clear element. (type `TagsInputClearProps`; optional)
- `itemProps`: Props forwarded to the item element. (type `TagsInputItemProps`; optional)
- `itemTextProps`: Props forwarded to the item text element. (type `TagsInputItemTextProps`; optional)
- `itemDeleteProps`: Props forwarded to the item delete element. (type `TagsInputItemDeleteProps`; optional)
- `dir`: The reading direction of the tags input. (type `Direction`; optional)
- `modelValue`: The controlled value of the tags input. (type `string[]`; optional)
- `defaultValue`: The uncontrolled default value of the tags input. (type `string[]`; optional)
- `addOnPaste`: Whether to add tags on paste. (type `boolean`; optional)
- `addOnTab`: Whether to add tags on tab. (type `boolean`; optional)
- `addOnBlur`: Whether to add tags on blur. (type `boolean`; optional)
- `duplicate`: Whether to allow duplicated tags. (type `boolean`; optional)
- `delimiter`: The delimiter used to add tags. (type `string | RegExp`; optional)
- `max`: Maximum number of tags. Set to 0 for unlimited. (type `number`; optional)
- `displayValue`: Display the value of the tag. Useful when you want to apply modifications to the value like adding a suffix (type `((value: string) => string)`; default `"(value: string) => value"`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the TagsInputCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string[]]`; parameters `value: string[]`)
- `invalid`: Emitted when invalid occurs. (type `[value: string]`; parameters `value: string`)
- `addTag`: Emitted when add tag occurs. (type `[value: string]`; parameters `value: string`)
- `removeTag`: Emitted when remove tag occurs. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the TagsInputCompact component.
- `item`: Custom item content or full item replacement. (type `((props: TagsInputCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for item-related compact slots.
- `value`: Value associated with the current item. (type `string`; required)
- `index`: Current item index. (type `number`; required)
- `displayedValue`: Current item display value. (type `string`; required)
- `onDelete`: Delete handler for the current item. (type `() => void`; required)
- `onClear`: Clear handler for the current item. (type `() => void`; required)

### TagsInputControl

- No documented props, emits, slots, or slot props were available.

### TagsInputItem

#### Props
Properties for the TagsInputItem component.
- `value`: Value associated with the tag. (type `string`; required)
- `disabled`: Whether to disable the tag item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TagsInputItemDelete

#### Props
Properties for the TagsInputItemDelete component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TagsInputItemText

#### Props
Properties for the TagsInputItemText component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TagsInputRoot

#### Props
Properties for the TagsInputRoot component.
- `dir`: The reading direction of the tags input. (type `Direction`; optional)
- `modelValue`: The controlled value of the tags input. (type `string[]`; optional)
- `defaultValue`: The uncontrolled default value of the tags input. (type `string[]`; optional)
- `addOnPaste`: Whether to add tags on paste. (type `boolean`; optional)
- `addOnTab`: Whether to add tags on tab. (type `boolean`; optional)
- `addOnBlur`: Whether to add tags on blur. (type `boolean`; optional)
- `duplicate`: Whether to allow duplicated tags. (type `boolean`; optional)
- `delimiter`: The delimiter used to add tags. (type `string | RegExp`; optional)
- `max`: Maximum number of tags. Set to 0 for unlimited. (type `number`; optional)
- `displayValue`: Display the value of the tag. Useful when you want to apply modifications to the value like adding a suffix (type `((value: string) => string)`; default `"(value: string) => value"`; optional)
- `id`: Id of the input element (type `string`; optional)
- `autofocus`: When `true`, the input is auto-focused. (type `boolean`; optional)
- `autocomplete`: The autocomplete attribute of the input. Supports the HTML autofill tokens (including password-manager values such as `current-password` / `new-password`), in addition to the `on` / `off` switches. (type `'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-...`; optional)
- `disabled`: When `true`, prevents the user from interacting with the input. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the input (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the input (type `number`; optional)
- `pattern`: The pattern attribute of the input (type `string`; optional)
- `placeholder`: The placeholder of the input (type `string`; optional)
- `readonly`: When `true`, the input is read-only. (type `boolean`; optional)
- `type`: The type of the input element. (type `InputTypeHTMLAttribute`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the TagsInputRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string[]]`; parameters `value: string[]`)
- `invalid`: Emitted when invalid occurs. (type `[value: string]`; parameters `value: string`)
- `addTag`: Emitted when add tag occurs. (type `[value: string]`; parameters `value: string`)
- `removeTag`: Emitted when remove tag occurs. (type `[value: string]`; parameters `value: string`)

## Notes

### Architecture and benchmark differences

`TagsInputRoot` owns the value via `useControllableState` and the collection registry (each `Item` registers through `useCollectionItem`). `TagsInputControl` only commits values: it watches delimiter/paste/Enter/Tab/blur, trims and validates through the root's `onAddValue`, and reports rejections via the `invalid` event. Keyboard selection state (`selectedElement`) lives on the root so the control's keydown handler can move selection with arrow keys (logical direction, RTL-aware) and remove tags with `Backspace`/`Delete`/`Home`/`End`. The compact iterates the value array with an `index-value` key so duplicated values stay stable without in-place value patching. Most benchmark libraries expose tags as a mode of a single select; the headless/styled split, per-part `*Props` passthrough, slot-driven item rendering, and the `invalid`/`addTag`/`removeTag` event surface are the differentiators.

| Capability                       | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :------------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split            |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled        |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   ✅   |
| Enter / delimiter / paste add    |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   ✅   |
| Keyboard tag selection + removal |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| RTL direction reversal           |    ✅     |     —      |      —       |    —    |    —     |   —    |
| `max` / `duplicate` constraints  |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `RegExp` delimiter               |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Per-part `*Props` passthrough    |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Custom item slot                 |    ✅     |     ✅     |      ✅      |   ✅    |    —     |   ✅   |
| Form hidden-input serialization  |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Localized `aria-label`s          |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |

### Cautions

- The value is always a `string[]`; duplicates are rejected unless `duplicate` is set. `displayValue` changes the label only — the stored value stays the raw string.
- `max={0}` means unlimited; any positive number caps the count and rejected additions emit `invalid` with the attempted value.
- `addOnBlur` commits pending text on blur, but a blur that lands on a tag's delete/clear button inside the tag list is skipped (guarded via `aria-controls`).
- `addOnTab` prevents the default tab-out and commits instead; if you need to leave the field, disable it or commit on blur.
- The compact renders the clear trigger whenever `clearable` is not `false`; the default styles hide it until the root has a value.
- In controlled mode (`modelValue` bound), the parent must update the bound array — the component only emits `update:modelValue`.
- `readonly` keeps the input read-only but still allows tag removal and clearing; use `disabled` to block all interaction.
- The input's `aria-controls` points at the derived tag-list container id (`{id}-tags-list`); pass an `id` to enable the blur guard and form-label association.

## FAQ

### How do I add tags on Enter only?

That's the default — type a value and press `Enter`. `Tab`/blur commit only when `addOnTab`/`addOnBlur` are enabled.

### How do I let users paste multiple tags at once?

Set `addOnPaste` and keep the default `delimiter=","` — pasting `"a,b,c"` creates three tags. Use a `RegExp` delimiter for flexible splits, e.g. `:delimiter="/[,，]/"`.

### How do I prevent duplicate tags?

Duplicates are rejected by default and emit `invalid` with the rejected value. Pass `duplicate` to allow repeats (the compact keys each item by its position so repeats stay stable).

### How does the value reach a form submission?

With `name` set, the values serialize into a visually hidden input (one per tag). Combined with `required`, an empty tag list marks the control invalid.

### Why did my controlled value not update?

In controlled mode the component only emits `update:modelValue`; you must rebind it (e.g. `v-model`) so the prop changes, otherwise the UI stays on the previous array.

## Textarea

- Page URL: /components/textarea
- Markdown URL: /components/textarea.md
- Description: A multi-line text input for longer free-form content, supporting auto-resizing, character counting, and clearable functionality. Use it for descriptions, comments, messages, or any content that spans multiple lines. For single-line input use SInput.

# Textarea

## Overview

A multi-line text input for longer free-form content, supporting auto-resizing, character counting, and clearable functionality. Use it for descriptions, comments, messages, or any content that spans multiple lines. For single-line input use `SInput`.

## Usage

Usage examples for textarea are rendered on the site.

## Features

- 📏 6 sizes: xs, sm, md, lg, xl, 2xl
- 📐 Autosize with `minRows` / `maxRows` bounds and overflow switching
- 🧹 Clearable mode with an i18n `aria-label` clear button
- 🔢 Character counter (`count / maxlength`) with and without `maxlength`
- 🔄 `resize` control: none / vertical / horizontal (ignored while autosize is active)
- 📋 Native form submission via a proxied hidden input when `name` is set
- 🧩 `clear` / `counter` / `footer` slots for per-part customization
- ♿ Full accessibility support — `aria-roledescription`, clear button naming, axe-clean

## Textarea component family

- **STextarea** - Base multi-line text area component
- **STextareaClear** - Clear button, shown on hover/focus when `clearable`

## Demos

Interactive demos for textarea are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (6): Textarea, TextareaClear, TextareaCompact, TextareaControl, TextareaCounter, TextareaRoot.

### Textarea

#### Props
Properties for the Textarea component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TextareaUi>`; optional)
- `resize`: The resize of the textarea if autosize is true, the resize will be ignored (type `TextareaResize`; optional)
- `textareaRef`: The function to set the textarea element. (type `((el: HTMLTextAreaElement) => void)`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `showCounter`: Whether to show the counter. (type `boolean`; default `false`; optional)
- `controlProps`: Properties forwarded to the control element. (type `TextareaControlProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `TextareaClearProps`; optional)
- `counterProps`: Properties forwarded to the counter element. (type `TextareaCounterProps`; optional)
- `defaultValue`: The default value of the textarea (type `string`; optional)
- `modelValue`: The controlled value of the textarea (type `string`; optional)
- `autosize`: When `true` or an options object, enables auto-resizing based on content (type `boolean | TextareaAutosizeOptions`; optional)
- `id`: Id of the textarea element (type `string`; optional)
- `autofocus`: When `true`, the textarea is auto-focused. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the textarea. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the textarea (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the textarea (type `number`; optional)
- `placeholder`: The placeholder of the textarea (type `string`; optional)
- `readonly`: When `true`, the textarea is read-only. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the Textarea component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the Textarea component.
- `clear`: Custom content for the clear slot. (type `((props: TextareaCompactSlotProps) => any) | undefined`)
- `counter`: Custom content for the counter slot. (type `((props: TextareaCompactSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: TextareaCompactSlotProps) => any) | undefined`)

### TextareaClear

#### Props
Properties for the TextareaClear component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the TextareaClear component.
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### TextareaCompact

#### Props
Properties for the TextareaCompact component.
- `textareaRef`: The function to set the textarea element. (type `((el: HTMLTextAreaElement) => void)`; optional)
- `clearable`: Whether to show the clear trigger. (type `boolean`; default `false`; optional)
- `showCounter`: Whether to show the counter. (type `boolean`; default `false`; optional)
- `controlProps`: Properties forwarded to the control element. (type `TextareaControlProps`; optional)
- `clearProps`: Properties forwarded to the clear element. (type `TextareaClearProps`; optional)
- `counterProps`: Properties forwarded to the counter element. (type `TextareaCounterProps`; optional)
- `defaultValue`: The default value of the textarea (type `string`; optional)
- `modelValue`: The controlled value of the textarea (type `string`; optional)
- `autosize`: When `true` or an options object, enables auto-resizing based on content (type `boolean | TextareaAutosizeOptions`; optional)
- `id`: Id of the textarea element (type `string`; optional)
- `autofocus`: When `true`, the textarea is auto-focused. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the textarea. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the textarea (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the textarea (type `number`; optional)
- `placeholder`: The placeholder of the textarea (type `string`; optional)
- `readonly`: When `true`, the textarea is read-only. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the TextareaCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `clear`: Emitted when the clear button is clicked. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)
#### Slots
Slots for the TextareaCompact component.
- `clear`: Custom content for the clear slot. (type `((props: TextareaCompactSlotProps) => any) | undefined`)
- `counter`: Custom content for the counter slot. (type `((props: TextareaCompactSlotProps) => any) | undefined`)
- `footer`: Custom content for the footer slot. (type `((props: TextareaCompactSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the TextareaCompact component.
- `modelValue`: Current model value. (type `string`; optional)
- `clear`: Clear handler. (type `() => void`; required)
- `count`: Current character count. (type `number`; required)
- `maxlength`: Current maxlength. (type `number`; optional)

### TextareaControl

- No documented props, emits, slots, or slot props were available.

### TextareaCounter

- No documented props, emits, slots, or slot props were available.

### TextareaRoot

#### Props
Properties for the TextareaRoot component.
- `defaultValue`: The default value of the textarea (type `string`; optional)
- `modelValue`: The controlled value of the textarea (type `string`; optional)
- `autosize`: When `true` or an options object, enables auto-resizing based on content (type `boolean | TextareaAutosizeOptions`; optional)
- `id`: Id of the textarea element (type `string`; optional)
- `autofocus`: When `true`, the textarea is auto-focused. (type `boolean`; optional)
- `disabled`: When `true`, prevents the user from interacting with the textarea. (type `boolean`; optional)
- `maxlength`: The maximum number of characters allowed in the textarea (type `number`; optional)
- `minlength`: The minimum number of characters allowed in the textarea (type `number`; optional)
- `placeholder`: The placeholder of the textarea (type `string`; optional)
- `readonly`: When `true`, the textarea is read-only. (type `boolean`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
#### Emits
Events for the TextareaRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)

## Notes

### Architecture and benchmark differences

SoybeanUI splits the textarea into a headless layer (`@soybeanjs/headless/textarea`) that owns state, autosize measurement, and form proxying, and a styled layer (`@soybeanjs/ui`) that owns variants and UnoCSS classes. The headless `TextareaCompact` composes `TextareaRoot` / `TextareaControl` / `TextareaClear` / `TextareaCounter` and exposes `clear` / `counter` / `footer` slots. This mirrors the headless/styled split of Radix and differs from single-package libraries such as Ant Design, Element Plus, and Mantine.

| Capability                    | SoybeanUI | Ant Design `Input.TextArea` | Element Plus `Input` | Mantine `Textarea` |
| :---------------------------- | :-------: | :-------------------------: | :------------------: | :----------------: |
| headless/styled split         |    ✅     |              —              |          —           |         —          |
| Controlled / uncontrolled     |    ✅     |             ✅              |          ✅          |         ✅         |
| Autosize (min/max rows)       |    ✅     |             ✅              |          ✅          |         ✅         |
| Clear button (hover reveal)   |    ✅     |              —              |          ✅          |         —          |
| Character counter `count/max` |    ✅     |             ✅              |          ✅          |         —          |
| `resize` control              |    ✅     |              —              |          ✅          |         ✅         |
| Native form proxying          |    ✅     |              —              |          —           |         —          |
| `footer` slot                 |    ✅     |              —              |          —           |         —          |
| `error` state                 |     —     |              —              |          ✅          |         ✅         |

### Cautions

- Autosize relies on real layout (`scrollHeight` / `getComputedStyle`); behavior is verified through browser e2e tests, not happy-dom unit tests.
- `error`, `loading`, `showCount`, IME composition events, and `change` events are not implemented; they are tracked as enhancement backlog.
- The counter does not announce itself with `aria-live`; add an `aria-live` region via the `counter` slot if live announcements are required.

## FAQ

### How do I make the textarea grow with its content?

Pass `autosize` (boolean) or `autosizeOptions` with `minRows` / `maxRows`. The height adjusts on input and switches to `overflow-y: auto` at `maxRows`.

### How do I show a character counter?

Pass `showCounter` with `maxlength` to show `count / maxlength`, or without `maxlength` to show the raw count. Customize the presentation via the `counter` slot.

### How do I control resizing?

Use the `resize` prop (`none` / `vertical` / `horizontal`). When `autosize` is active, `resize` is ignored because height is managed automatically.

### How does the textarea submit its value in a native form?

Pass `name` — the component renders a visually hidden proxy input carrying the current value, so native form submission works without extra wiring.

## ThemeModeSegment

- Page URL: /components/theme-mode-segment
- Markdown URL: /components/theme-mode-segment.md
- Description: SThemeModeSegment is a context-bound segmented control bound to the active SConfigProvider theme. It exposes the three ThemeModePreference options — auto (follows the OS prefers-color-scheme), light, and dark — as icon-led segment options, letting users pick a color scheme preference directly. Visual props are inherited from the Segment component, with shape defaulting to rounded.

# ThemeModeSegment

## Overview

`SThemeModeSegment` is a context-bound segmented control bound to the active `SConfigProvider` theme. It exposes the three `ThemeModePreference` options — `auto` (follows the OS `prefers-color-scheme`), `light`, and `dark` — as icon-led segment options, letting users pick a color scheme preference directly. Use it when all three preferences should be visible at a glance, such as in a header, settings panel, or customizer.

## Usage

Usage examples for theme-mode-segment are rendered on the site.

## Features

- 🌓 Three options — `auto` / `light` / `dark`, matching the theme `mode` type
- 🎚 Selection writes the preference through the shared theme context
- 🎨 Inherits `Segment` visual props (`size` / `shape` / `fill` / …), with `shape` defaulting to `rounded`
- 🖼 Scheme icons (monitor / sun / moon) are always rendered; `showLabel` adds the localized label next to them (hidden labels still provide accessible names)

## Demos

Interactive demos for theme-mode-segment are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): ThemeModeSegment.

### ThemeModeSegment

#### Props
Properties for the ThemeModeSegment component.

A context-bound segmented control bound to the active `SConfigProvider`
theme. It exposes the three `ThemeModePreference` options — `auto` (follows
the OS `prefers-color-scheme`), `light`, and `dark` — as icon-led segment
options. Visual props are inherited from `SegmentProps` (with `shape`
defaulting to `rounded`); `items`, `modelValue`, and `defaultValue` are not
exposed — the option list is fixed and the state is owned by the theme
context shared across all theme components.
- `showLabel`: Whether to render the localized label next to the scheme icon. When `false`, the label stays visually hidden so each option keeps an accessible name. (type `boolean`; default `false`; optional)
- `unmountOnHide`: When `true`, the element will be unmounted on closed state. (type `boolean`; default ``true``; optional)
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `dir`: The direction of navigation between items. (type `Direction`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `fill`: Fill. (type `SegmentFill`; optional)
- `shape`: Shape of the component. (type `SegmentShape`; optional)
- `loop`: Whether keyboard navigation should loop around (type `boolean`; default `false`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `SegmentTriggerProps`; optional)
- `orientation`: The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down) (type `DataOrientation`; optional)
- `listProps`: Properties forwarded to the list element. (type `SegmentListProps`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<SegmentUi>`; optional)
- `enableIndicator`: Whether to enable indicator. (type `boolean`; optional)
- `indicatorProps`: Properties forwarded to the indicator element. (type `SegmentIndicatorProps`; optional)
- `activationMode`: Whether a tab is activated automatically (on focus) or manually (on click). (type `TabsActivationMode`; default `automatic`; optional)

## Notes

### Scope

Like `SThemeModeSelect` and `SThemeModeSwitch`, `SThemeModeSegment` is a theme-layer component that operates on the theme context from a parent `SConfigProvider`. It does not accept a `modelValue`; the preference is owned by the provider and shared across all theme components. It is the segmented counterpart of `SThemeModeSelect` — same three options, no dropdown.

### Cautions

- The component must be rendered inside a `SConfigProvider`, otherwise `useTheme` throws.
- `auto` is a _preference_ — the resolved scheme (`light` / `dark`) still depends on the OS `prefers-color-scheme` and is exposed as `effectiveMode` on the theme context.
- `items`, `modelValue`, and `defaultValue` are not exposed: the option list is fixed and the state lives in the theme context.

## ThemeModeSelect

- Page URL: /components/theme-mode-select
- Markdown URL: /components/theme-mode-select.md
- Description: SThemeModeSelect is a context-bound dropdown bound to the active SConfigProvider theme. It exposes the three ThemeModePreference options — auto (follows the OS prefers-color-scheme), light, and dark — each with a scheme icon, letting users pick a color scheme preference directly.

# ThemeModeSelect

## Overview

`SThemeModeSelect` is a context-bound dropdown bound to the active `SConfigProvider` theme. It exposes the three `ThemeModePreference` options — `auto` (follows the OS `prefers-color-scheme`), `light`, and `dark` — each with a scheme icon, letting users pick a color scheme preference directly.

## Usage

Usage examples for theme-mode-select are rendered on the site.

## Features

- 🌓 Three options — `auto` / `light` / `dark`, matching the theme `mode` type
- 🎚 Selection writes the preference through the shared theme context
- 🎨 Inherits `size` from the theme, with per-option scheme icons by default
- 🧩 `showIcon` toggles the monitor / sun / moon glyphs in the trigger and options

## Demos

Interactive demos for theme-mode-select are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): ThemeModeSelect.

### ThemeModeSelect

#### Props
Properties for the ThemeModeSelect component.

A context-bound dropdown bound to the active `SConfigProvider` theme. It
offers the three `ThemeModePreference` options — `auto` (follows the OS
`prefers-color-scheme`), `light`, and `dark`.
- `size`: Visual size of the select trigger. (type `ThemeSize`; default `'md'`; optional)
- `showIcon`: Whether to render a scheme icon (monitor / sun / moon) in the trigger and each option. (type `boolean`; default `true`; optional)

## Notes

### Scope

Like `SThemeModeSwitch`, `SThemeModeSelect` is a theme-layer component that operates on the theme context from a parent `SConfigProvider`. It does not accept a `modelValue`; the preference is owned by the provider and shared across all theme components.

### Cautions

- The component must be rendered inside a `SConfigProvider`, otherwise `useTheme` throws.
- `auto` is a _preference_ — the resolved scheme (`light` / `dark`) still depends on the OS `prefers-color-scheme` and is exposed as `effectiveMode` on the theme context.

## ThemeModeSwitch

- Page URL: /components/theme-mode-switch
- Markdown URL: /components/theme-mode-switch.md
- Description: SThemeModeSwitch is a context-bound toggle bound to the active SConfigProvider theme. It reflects the current _effective_ scheme (so an auto preference shows the OS-resolved light/dark state) and pins an explicit light / dark preference when toggled. Use it as a quick, compact light/dark switch in a header or toolbar.

# ThemeModeSwitch

## Overview

`SThemeModeSwitch` is a context-bound toggle bound to the active `SConfigProvider` theme. It reflects the current _effective_ scheme (so an `auto` preference shows the OS-resolved light/dark state) and pins an explicit `light` / `dark` preference when toggled. Use it as a quick, compact light/dark switch in a header or toolbar.

## Usage

Usage examples for theme-mode-switch are rendered on the site.

## Features

- 🌓 Reflects the _effective_ scheme — with `auto`, the thumb tracks the OS `prefers-color-scheme`
- 🎚 Pins an explicit preference on toggle, overriding any `auto` resolution
- 🎨 Inherits `size` and `color` from the theme, with a sun/moon icon by default
- ♿ Forwards an accessible label to the `role="switch"` control (`axe`-clean)
- 🧩 `showIcon` toggles the sun/moon glyph

## Demos

Interactive demos for theme-mode-switch are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): ThemeModeSwitch.

### ThemeModeSwitch

#### Props
Properties for the ThemeModeSwitch component.

A context-bound toggle bound to the active `SConfigProvider` theme. It shows
the current *effective* scheme (so an `auto` preference is reflected as the
OS-resolved light/dark) and pins an explicit `light` / `dark` preference when
toggled. To restore `auto`, use `SThemeModeSelect`.
- `size`: Visual size of the switch. (type `ThemeSize`; default `'md'`; optional)
- `color`: Theme color of the switch track. (type `ThemeColor`; default `'accent'`; optional)
- `showIcon`: Whether to render a sun/moon icon inside the switch thumb. (type `boolean`; default `true`; optional)
- `aria-label`: Accessible label for the switch control. (type `string`; default `'Toggle color scheme'`; optional)

## Notes

### Scope

`SThemeModeSwitch` is a theme-layer component that operates directly on the theme context from a parent `SConfigProvider`. It does not accept a `modelValue`; state is owned by the provider and shared across all theme components. To select `auto` (which a binary switch cannot express), pair it with `SThemeModeSelect`.

### Cautions

- The component must be rendered inside a `SConfigProvider` that provides the theme context, otherwise `useTheme` throws.
- Toggling a switch that is currently following `auto` pins an explicit `light` / `dark` preference; use `SThemeModeSelect` to return to `auto`.

## TimeField

- Page URL: /components/time-field
- Markdown URL: /components/time-field.md
- Description: A segmented time input that renders individually editable hour, minute, and optional second and day-period segments while submitting a native form value. Use it whenever a user must enter a time fast and precisely — scheduling, booking, time-window filtering, or any form that needs a validated time. For a date with a time, use SDateField with granularity: 'minute'; for a range, prefer STimeRangeField.

# TimeField

## Overview

A segmented time input that renders individually editable hour, minute, and optional second and day-period segments while submitting a native form value. Use it whenever a user must enter a time fast and precisely — scheduling, booking, time-window filtering, or any form that needs a validated time. For a date with a time, use `SDateField` with `granularity: 'minute'`; for a range, prefer `STimeRangeField`.

## Usage

Usage examples for time-field are rendered on the site.

## Features

- 🕐 Segmented editing — hour, minute, and optional second and day-period segments, each an editable `role="spinbutton"`
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` for the value, backed by `useControllableState`
- 🕛 12/24-hour cycle — `hourCycle` switches between `AM/PM` and 24-hour display per locale, with day-period segment editing
- ⌨️ Full keyboard support — digit typing with auto-advance, `ArrowUp`/`ArrowDown` increment/decrement, `ArrowLeft`/`ArrowRight` segment navigation with RTL reversal
- ⛓ Time validation — `minValue`/`maxValue`/`isTimeUnavailable` mark the root `data-invalid`
- 📝 Native form value — a visually hidden `input[type="time"]` carries the ISO value to its owning form
- ⚙️ Granularity & step — `granularity` (hour/minute/second) and `step` control which segments render and the increment per arrow
- 🧩 Composable slots — `leading`/`trailing` place content around the segments
- 🚫 Disabled / readonly — both states block editing and render proper `data-*`/`aria-*` attributes

## Component family

- `STimeField` — the styled wrapper that forwards props to the headless compact and injects `dateFieldVariants` (shared with `SDateField`) classes
- `TimeFieldCompact` (headless) — data-driven composition of `TimeFieldRoot` + one `TimeFieldInput` per segment, plus `leading`/`trailing` slots; import from `@soybeanjs/headless/time-field` for unstyled usage
- `TimeFieldRoot` / `TimeFieldInput` (headless) — the state owner (segment values, validation, hidden input, focus management) and a single editable segment bound to the shared `useDateField` composable

## Demos

Interactive demos for time-field are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): TimeField, TimeFieldCompact, TimeFieldInput, TimeFieldRoot.

### TimeField

#### Props
Properties for the TimeField component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TimeFieldUi>`; optional)
- `inputProps`: Properties forwarded to the input element. (type `TimeFieldInputProps`; optional)
- `defaultValue`: Default value for the time field. (type `Date`; optional)
- `modelValue`: Current model value. (type `Date`; optional)
- `defaultPlaceholder`: Default placeholder. (type `Date`; optional)
- `placeholder`: Placeholder. (type `Date`; optional)
- `granularity`: Granularity. (type `TimeGranularity`; optional)
- `maxValue`: Max value. (type `Date`; optional)
- `minValue`: Min value. (type `Date`; optional)
- `isTimeUnavailable`: Whether the time is unavailable. (type `TimeMatcher`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
#### Emits
Events for the TimeField component.
- `update:modelValue`: Emitted when the model value changes. (type `[time: Date | undefined]`; parameters `time: Date | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[time: Date]`; parameters `time: Date`)
#### Slots
Slots for the TimeField component.
- `leading`: Content rendered before the time segments. (type `(() => any) | undefined`)
- `trailing`: Content rendered after the time segments. (type `(() => any) | undefined`)

### TimeFieldCompact

#### Props
Properties for the time field compact component.
- `inputProps`: Properties forwarded to the input element. (type `TimeFieldInputProps`; optional)
- `defaultValue`: Default value for the time field. (type `Date`; optional)
- `modelValue`: Current model value. (type `Date`; optional)
- `defaultPlaceholder`: Default placeholder. (type `Date`; optional)
- `placeholder`: Placeholder. (type `Date`; optional)
- `granularity`: Granularity. (type `TimeGranularity`; optional)
- `maxValue`: Max value. (type `Date`; optional)
- `minValue`: Min value. (type `Date`; optional)
- `isTimeUnavailable`: Whether the time is unavailable. (type `TimeMatcher`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
#### Emits
Events for the time field compact component.
- `update:modelValue`: Emitted when the model value changes. (type `[time: Date | undefined]`; parameters `time: Date | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[time: Date]`; parameters `time: Date`)
#### Slots
Slots for the TimeFieldCompact component.
- `leading`: Content rendered before the time segments. (type `(() => any) | undefined`)
- `trailing`: Content rendered after the time segments. (type `(() => any) | undefined`)

### TimeFieldInput

- No documented props, emits, slots, or slot props were available.

### TimeFieldRoot

#### Props
Properties for the TimeFieldRoot component.
- `defaultValue`: Default value for the time field. (type `Date`; optional)
- `modelValue`: Current model value. (type `Date`; optional)
- `defaultPlaceholder`: Default placeholder. (type `Date`; optional)
- `placeholder`: Placeholder. (type `Date`; optional)
- `granularity`: Granularity. (type `TimeGranularity`; optional)
- `maxValue`: Max value. (type `Date`; optional)
- `minValue`: Min value. (type `Date`; optional)
- `isTimeUnavailable`: Whether the time is unavailable. (type `TimeMatcher`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
#### Emits
Events for the TimeFieldRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[time: Date | undefined]`; parameters `time: Date | undefined`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[time: Date]`; parameters `time: Date`)
#### Slots
Slots for the TimeFieldRoot component.
- `default`: No description. (type `((props: TimeFieldRootSlotProps) => any) | undefined`)
#### Slot Props
Slot properties for the TimeFieldRoot component.
- `modelValue`: Current model value. (type `Date | undefined`; required)
- `segments`: Segments used by the default slot. (type `DateFieldSegment[]`; required)
- `isInvalid`: Whether the current value is invalid. (type `boolean`; required)

## Notes

### Architecture and benchmark differences

`TimeFieldRoot` owns the `TimeValue` via `useControllableState`, keeps `segmentValues` as a shallowRef, and runs validation through `isInvalid`. Each `TimeFieldInput` binds the same `useDateField` composable used by the `date-field` family for per-part keydown logic; `TimeFieldCompact` iterates the segments produced by `createContent` and renders one input each, with `leading`/`trailing` slots around them. Focus movement is handled by the root's `moveFocus`, mapping the physical arrow key from `dir` so RTL swaps `ArrowLeft`/`ArrowRight`. Most benchmark libraries ship a plain text input or select-based picker; the segmented spinbutton pattern with keyboard increment/typing and the headless/styled split are the differentiators.

| Capability                   | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :--------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split        |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Segmented editable segments  |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled    |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| 12/24-hour cycle             |    ✅     |     ✅     |      ✅      |    —    |    ✅    |   —    |
| Keyboard increment/typing    |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Segment navigation + RTL     |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Range validation             |    ✅     |     ✅     |      —       |    —    |    —     |   —    |
| `isTimeUnavailable`          |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Granularity (second)         |    ✅     |     ✅     |      ✅      |    —    |    ✅    |   —    |
| Configurable step            |    ✅     |     ✅     |      ✅      |    —    |    —     |   —    |
| Native form value            |    ✅     |     —      |      —       |   ✅    |    —     |   —    |
| `leading` / `trailing` slots |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Disabled / readonly          |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |

### Cautions

- The value is a `TimeValue` — a native `Date` whose hour/minute/second parts are meaningful (the date part is normalized), not a `string`. Use it with the other date-family components.
- `defaultValue` is only read on mount — use `v-model` for external control.
- When the value is empty the segments display the placeholder time (derived from `defaultValue`/`defaultPlaceholder` or the current time) — the submitted form value is still empty until the user types.
- `granularity` defaults to `'minute'`; pass `'second'` for seconds segments or `'hour'` to hide the minute segment.
- `hourCycle` (`12`/`24`) controls the day-period segment and the accessible hour range; leave it unset to follow the locale.
- Time validation marks the root `data-invalid` but never clamps the value — clear or correct it in the parent.

## FAQ

### How do I edit a time with the keyboard?

Tab into the field and type digits — after the segment fills it advances automatically. `ArrowUp`/`ArrowDown` increment or decrement the focused segment, `ArrowLeft`/`ArrowRight` move between segments (reversed in RTL), and `Backspace` clears digits. On a 12-hour cycle `a`/`p` toggles `AM`/`PM`.

### How do I show seconds or hide the minute segment?

Pass `granularity: 'second'` to render hour, minute, and second segments, or `granularity: 'hour'` to render only the hour segment.

### How do I switch between 12-hour and 24-hour display?

Pass `hourCycle: 12` or `hourCycle: 24`. Leave it unset to follow the active locale.

### How do I restrict the selectable time?

Pass `minValue`/`maxValue` — times outside are marked `data-invalid` and rejected. `isTimeUnavailable` accepts a predicate for arbitrary exclusions.

### How is `STimeField` different from `SDateField` with `granularity: 'minute'`?

`STimeField` is a pure time input — it never renders date segments. `SDateField` with a time granularity renders the full date and time together (for example `2026/04/19 14:30`) and accepts a `{ date, time }` value.

## TimeRangeField

- Page URL: /components/time-range-field
- Markdown URL: /components/time-range-field.md
- Description: A segmented time range input with independently editable start and end time segments (hour, minute, and optional second and day-period) while still submitting native form values for both sides. Use it whenever a user must enter a start and end time quickly and precisely — scheduling, booking, shift or time-window filtering. For a single time use STimeField; for a date and time range use SDateRangeField with a time granularity or SDateRangePicker.

# TimeRangeField

## Overview

A segmented time range input with independently editable start and end time segments (hour, minute, and optional second and day-period) while still submitting native form values for both sides. Use it whenever a user must enter a start and end time quickly and precisely — scheduling, booking, shift or time-window filtering. For a single time use `STimeField`; for a date and time range use `SDateRangeField` with a time granularity or `SDateRangePicker`.

## Usage

Usage examples for time-range-field are rendered on the site.

## Features

- ⏱ Two segmented groups — independent start/end hour, minute, and optional second and day-period segments, each an editable `role="spinbutton"`
- 🎚 Controlled / uncontrolled — `v-model`/`defaultValue` for the whole `{ start, end }` range, backed by `useControllableState`
- 🕛 12/24-hour cycle — `hourCycle` switches between `AM/PM` and 24-hour display per locale, with day-period segment editing on both sides
- ⌨️ Full keyboard support — digit typing with auto-advance, `ArrowUp`/`ArrowDown` increment/decrement, `ArrowLeft`/`ArrowRight` navigation that crosses group boundaries and reverses in RTL
- ⛓ Range validation — `start ≤ end` is enforced, plus `minValue`/`maxValue`/`isTimeUnavailable` mark the root `data-invalid`
- 📝 Two native form values — visually hidden `input[type="time"]` elements carry both sides under `startName`/`endName`
- ⚙️ Granularity & step — `granularity` (hour/minute/second) and `step` control which segments render and the increment per arrow
- 🧩 Composable slots — `leading`/`trailing` place content around the groups and `separator` customizes the divider between them
- 🚫 Disabled / readonly — both states block editing on every segment and render proper `data-*`/`aria-*` attributes

## Component family

- `STimeRangeField` — the styled wrapper that forwards props to the headless compact and injects `dateRangeFieldVariants` (shared with `SDateRangeField`) classes
- `TimeRangeFieldCompact` (headless) — data-driven composition of `TimeRangeFieldRoot` + one `TimeRangeFieldInput` per segment in two groups, plus `leading`/`separator`/`trailing` slots; import from `@soybeanjs/headless/time-range-field` for unstyled usage
- `TimeRangeFieldRoot` / `TimeRangeFieldInput` (headless) — the state owner (segment values, range validation, two hidden inputs, cross-group focus management) and a single editable segment bound to the shared `useDateField` composable

## Demos

Interactive demos for time-range-field are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): TimeRangeField, TimeRangeFieldCompact, TimeRangeFieldInput, TimeRangeFieldRoot.

### TimeRangeField

#### Props
Properties for the TimeRangeField component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TimeRangeFieldUi>`; optional)
- `inputProps`: Properties forwarded to the input element. (type `TimeRangeFieldInputProps`; optional)
- `separator`: Separator. (type `string`; optional)
- `defaultValue`: Default value. (type `TimeRange`; optional)
- `modelValue`: Current model value. (type `TimeRange`; optional)
- `startName`: Start name. (type `string`; optional)
- `endName`: End name. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `placeholder`: Placeholder. (type `Date`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `Date`; optional)
- `maxValue`: Max value. (type `Date`; optional)
- `minValue`: Min value. (type `Date`; optional)
- `granularity`: Granularity. (type `TimeGranularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
- `isTimeUnavailable`: Whether the time is unavailable. (type `TimeMatcher`; optional)
#### Emits
Events for the TimeRangeField component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: TimeRange]`; parameters `range: TimeRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[time: Date]`; parameters `time: Date`)
- `update:startValue`: Emitted when the start value changes. (type `[time: Date | null]`; parameters `time: Date | null`)
- `update:endValue`: Emitted when the end value changes. (type `[time: Date | null]`; parameters `time: Date | null`)
#### Slots
Slots for the TimeRangeField component.
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `(() => any) | undefined`)
#### Slot Props
Slot Props for the TimeRangeField component.
- `modelValue`: Current model value. (type `TimeRange`; required)
- `startSegments`: Start segments. (type `DateFieldSegment[]`; required)
- `endSegments`: End segments. (type `DateFieldSegment[]`; required)
- `isInvalid`: Whether the field is invalid. (type `boolean`; required)

### TimeRangeFieldCompact

#### Props
Properties for the TimeRangeFieldCompact component.
- `inputProps`: Properties forwarded to the input element. (type `TimeRangeFieldInputProps`; optional)
- `separator`: Separator. (type `string`; optional)
- `defaultValue`: Default value. (type `TimeRange`; optional)
- `modelValue`: Current model value. (type `TimeRange`; optional)
- `startName`: Start name. (type `string`; optional)
- `endName`: End name. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `placeholder`: Placeholder. (type `Date`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `Date`; optional)
- `maxValue`: Max value. (type `Date`; optional)
- `minValue`: Min value. (type `Date`; optional)
- `granularity`: Granularity. (type `TimeGranularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
- `isTimeUnavailable`: Whether the time is unavailable. (type `TimeMatcher`; optional)
#### Emits
Events for the TimeRangeFieldCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: TimeRange]`; parameters `range: TimeRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[time: Date]`; parameters `time: Date`)
- `update:startValue`: Emitted when the start value changes. (type `[time: Date | null]`; parameters `time: Date | null`)
- `update:endValue`: Emitted when the end value changes. (type `[time: Date | null]`; parameters `time: Date | null`)
#### Slots
Slots for the TimeRangeFieldCompact component.
- `leading`: Custom content for the leading slot. (type `(() => any) | undefined`)
- `trailing`: Custom content for the trailing slot. (type `(() => any) | undefined`)
- `separator`: Custom content for the separator slot. (type `(() => any) | undefined`)

### TimeRangeFieldInput

#### Props
Properties for the TimeRangeFieldInput component.
- `type`: Type. (type `'start' | 'end'`; optional)
- `part`: Part. (type `import("../../date").EditableSegmentPart | import("../../date").NonEditableSegmentPart`; required)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TimeRangeFieldRoot

#### Props
Properties for the TimeRangeFieldRoot component.
- `defaultValue`: Default value. (type `TimeRange`; optional)
- `modelValue`: Current model value. (type `TimeRange`; optional)
- `startName`: Start name. (type `string`; optional)
- `endName`: End name. (type `string`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `id`: Id. (type `string`; optional)
- `placeholder`: Placeholder. (type `Date`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `readonly`: Whether the component is readonly. (type `boolean`; optional)
- `step`: Step. (type `DateStep`; optional)
- `locale`: Locale. (type `string`; optional)
- `defaultPlaceholder`: Default placeholder. (type `Date`; optional)
- `maxValue`: Max value. (type `Date`; optional)
- `minValue`: Min value. (type `Date`; optional)
- `granularity`: Granularity. (type `TimeGranularity`; optional)
- `hourCycle`: Hour cycle. (type `12 | 24`; optional)
- `hideTimeZone`: Whether hide time zone. (type `boolean`; optional)
- `isTimeUnavailable`: Whether the time is unavailable. (type `TimeMatcher`; optional)
#### Emits
Events for the TimeRangeFieldRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[range: TimeRange]`; parameters `range: TimeRange`)
- `update:placeholder`: Emitted when the placeholder value changes. (type `[time: Date]`; parameters `time: Date`)
- `update:startValue`: Emitted when the start value changes. (type `[time: Date | null]`; parameters `time: Date | null`)
- `update:endValue`: Emitted when the end value changes. (type `[time: Date | null]`; parameters `time: Date | null`)
#### Slots
Slots for the TimeRangeField component.
- `default`: Custom content for the default slot. (type `((props: TimeRangeFieldSlotProps) => any) | undefined`)

## Notes

### Architecture and benchmark differences

`TimeRangeFieldRoot` owns the `TimeRange` via `useControllableState`, keeps `startSegmentValues`/`endSegmentValues` as two shallowRefs, and runs range validation through `isInvalid` (start after end, `minValue`/`maxValue`, `isTimeUnavailable`). Each `TimeRangeFieldInput` binds the same `useDateField` composable used by the `date-field` family; `TimeRangeFieldCompact` iterates the segments produced by `createContent` and renders one input per segment inside two `data-time-range-field-part` groups separated by the `separator` slot. Cross-group focus movement is handled by the root's `moveFocus`, mapping the physical arrow key from `dir` so RTL swaps `ArrowLeft`/`ArrowRight` — the group boundary is crossed on the physical direction (`delta`), not the semantic key. Most benchmark libraries ship two independent text inputs (or a plain picker); the dual segmented spinbutton groups with cross-boundary keyboard navigation and the headless/styled split are the differentiators.

| Capability                     | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn |
| :----------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :----: |
| headless/styled split          |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Dual segmented editable groups |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Cross-group focus movement     |    ✅     |     —      |      —       |    —    |    —     |   —    |
| RTL direction reversal         |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Controlled / uncontrolled      |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| Keyboard increment/typing      |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Range validation (start ≤ end) |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |
| `isTimeUnavailable`            |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Granularity (second)           |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Two native form values         |    ✅     |     ✅     |      ✅      |   ✅    |    —     |   —    |
| Separator prop / slot          |    ✅     |     —      |      —       |    —    |    —     |   —    |
| Disabled / readonly            |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |   —    |

### Cautions

- The value is a `TimeRange` — `{ start, end }` of `TimeValue`s (native `Date`s whose time-of-day parts are meaningful), not `string`s. Use it with the other date-family components.
- `defaultValue` is only read on mount — use `v-model` for external control.
- When a side is empty its segments display the placeholder time (derived from `defaultValue`/`defaultPlaceholder` or the current time) — the submitted form value is still empty until the user types.
- `granularity` defaults to `'minute'`; pass `'second'` for seconds segments on both sides.
- `hourCycle` (`12`/`24`) controls the day-period segments and the accessible hour range; leave it unset to follow the locale.
- Range validation marks the root `data-invalid` but never clamps the value — clear or correct it in the parent.
- The two hidden inputs share `required`; if you need per-side submit names pass `startName`/`endName` (falling back to `name` for the start side).

## FAQ

### How do I edit the range with the keyboard?

Tab into either group and type digits — after a segment fills it advances automatically. `ArrowUp`/`ArrowDown` increment or decrement the focused segment, and `ArrowLeft`/`ArrowRight` move between segments — including across the start/end boundary — reversed in RTL. On a 12-hour cycle `a`/`p` toggles `AM`/`PM`.

### How do I show seconds on both sides?

Pass `granularity: 'second'` to render hour, minute, and second segments in the start and end groups.

### How do I customize the separator between start and end?

Pass `separator: '→'` as a prop for a simple text divider, or use the `separator` slot to render any content (an icon, for example).

### How do I enforce that end is after start?

The component marks the root `data-invalid` automatically when `end` is before `start`. Combine with `minValue`/`maxValue`/`isTimeUnavailable` for arbitrary constraints — validation never clamps the value, so correct it in the parent.

### How is `STimeRangeField` different from `SDateRangeField`?

`STimeRangeField` is a pure time range input — it never renders date segments. `SDateRangeField` renders full dates (with optional time via granularity) and accepts `DateValue` pairs.

## Toast

- Page URL: /components/toast
- Markdown URL: /components/toast.md
- Description: Transient notifications that appear in a viewport and auto-dismiss. SToastProvider renders the toast viewports and the toast imperative API creates, updates, dismisses, and inspects notifications. It supports six types, six positions, stacking/expansion, swipe-to-dismiss, promise toasts, rich color and inverted themes, and a keyboard hotkey to focus the list.

# Toast

## Overview

Transient notifications that appear in a viewport and auto-dismiss. `SToastProvider` renders the toast viewports and the `toast` imperative API creates, updates, dismisses, and inspects notifications. It supports six types, six positions, stacking/expansion, swipe-to-dismiss, promise toasts, rich color and inverted themes, and a keyboard hotkey to focus the list.

Use it for global, non-blocking feedback (saved, errors, upload progress). Prefer `alert` for inline callouts near content, and `dialog` for blocking confirmations that need a decision.

## Usage

Mount one `SToastProvider` near your app root. If your app is already wrapped with `SConfigProvider`, a default `SToastProvider` is rendered automatically unless `customToast` is set to `true`.

Usage examples for toast are rendered on the site.

## Features

- ⚡ Imperative API — `toast()` plus `toast.success/error/warning/info/loading/custom/message/promise/dismiss`
- 🎨 6 types — `default`/`success`/`info`/`warning`/`error`/`loading` with default icons
- 📍 6 positions — `top-left`/`top-right`/`top-center`/`bottom-left`/`bottom-right`/`bottom-center`
- 🗂️ Stacking — `visibleCounts` limits visible toasts per position; hover expands the stack (`defaultExpanded`)
- 👆 Swipe to dismiss — drag left/right/up/down (configurable `swipeDirections`) to remove
- ⏱️ Auto-dismiss — `duration` per toast/provider; `0` or `Infinity` disables; pauses on hover and hidden-tab
- 🔮 Promise toasts — `toast.promise(promise, { loading, success, error })` with HTTP/Error handling
- 🎛️ Actions — `action`/`cancel` buttons with callbacks; `custom` for fully custom content
- ♿ Accessible — `aria-live="polite"` region, focus management with focus return, and a hotkey (default `Alt+T`) to focus the list

## Component family

- `SToastProvider` (styled) — the entry provider; injects `toastVariants` and the animation stylesheet
- `ToastProvider` (headless) — thin wrapper over `Toaster`
- `Toaster` (headless) — the state owner; subscribes to `ToastState`, manages stack/expand/focus, renders the 6 viewports
- `Toast` (headless) — a single toast; auto-close timer, swipe logic, height measurement, action/cancel/close
- `toast` (imperative) — the shared `toast` controller (`ToastState` observer) exposed on `@soybeanjs/ui`

## Demos

Interactive demos for toast are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (2): Toaster, ToastProvider.

### Toaster

#### Props
Properties for the Toaster component.
- `id`: Id. (type `string`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `hotkey`: Hotkey. (type `string[]`; optional)
- `customAriaLabel`: Custom aria label. (type `string`; optional)
- `containerAriaLabel`: Container aria label. (type `string`; optional)
- `position`: Position. (type `ToastPosition`; optional)
- `defaultExpanded`: Whether default expanded. (type `boolean`; optional)
- `duration`: The duration (in milliseconds) before the toast automatically closes. Set to `0` or `Infinity` to disable auto-dismissal. (type `number`; optional)
- `gap`: Gap. (type `number`; optional)
- `offset`: The maximum number of visible toasts per position. (type `ToastOffset`; default `3`; optional)
- `visibleCounts`: Visible counts. (type `number`; optional)
- `swipeDirections`: Swipe directions. (type `SwipeDirection[]`; optional)
- `showIcon`: Whether to show an icon. (type `boolean`; optional)
- `showClose`: Whether toasts show a close button by default. A toast-level `showClose` takes precedence over this default. (type `boolean`; default `true`; optional)
- `icons`: Icons. (type `Partial<Record<ToastIconType, IconValue>>`; optional)
- `toastProps`: Properties forwarded to the toast element. (type `LiHTMLAttributes`; optional)
- `wrapperProps`: Properties forwarded to the wrapper element. (type `HTMLAttributes`; optional)
- `contentProps`: Properties forwarded to the content element. (type `HTMLAttributes`; optional)
- `titleProps`: Properties forwarded to the title element. (type `HTMLAttributes`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `HTMLAttributes`; optional)
- `iconProps`: Properties forwarded to the icon component. (type `HTMLAttributes`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `HTMLAttributes`; optional)
- `actionProps`: Properties forwarded to the action element. (type `HTMLAttributes`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `HTMLAttributes`; optional)
- `closeProps`: Properties forwarded to the close element. (type `HTMLAttributes`; optional)

### ToastProvider

#### Props
Properties for the ToastProvider component.
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `ToastUi`; optional)
- `id`: Id. (type `string`; optional)
- `dir`: Reading direction of the component. (type `Direction`; optional)
- `hotkey`: Hotkey. (type `string[]`; optional)
- `customAriaLabel`: Custom aria label. (type `string`; optional)
- `containerAriaLabel`: Container aria label. (type `string`; optional)
- `position`: Position. (type `ToastPosition`; optional)
- `defaultExpanded`: Whether default expanded. (type `boolean`; optional)
- `duration`: The duration (in milliseconds) before the toast automatically closes. Set to `0` or `Infinity` to disable auto-dismissal. (type `number`; optional)
- `gap`: Gap. (type `number`; optional)
- `offset`: The maximum number of visible toasts per position. (type `ToastOffset`; default `3`; optional)
- `visibleCounts`: Visible counts. (type `number`; optional)
- `swipeDirections`: Swipe directions. (type `SwipeDirection[]`; optional)
- `showIcon`: Whether to show an icon. (type `boolean`; optional)
- `showClose`: Whether toasts show a close button by default. A toast-level `showClose` takes precedence over this default. (type `boolean`; default `true`; optional)
- `icons`: Icons. (type `Partial<Record<ToastIconType, IconValue>>`; optional)
- `toastProps`: Properties forwarded to the toast element. (type `LiHTMLAttributes`; optional)
- `wrapperProps`: Properties forwarded to the wrapper element. (type `HTMLAttributes`; optional)
- `contentProps`: Properties forwarded to the content element. (type `HTMLAttributes`; optional)
- `titleProps`: Properties forwarded to the title element. (type `HTMLAttributes`; optional)
- `descriptionProps`: Properties forwarded to the description element. (type `HTMLAttributes`; optional)
- `iconProps`: Properties forwarded to the icon component. (type `HTMLAttributes`; optional)
- `footerProps`: Properties forwarded to the footer element. (type `HTMLAttributes`; optional)
- `actionProps`: Properties forwarded to the action element. (type `HTMLAttributes`; optional)
- `cancelProps`: Properties forwarded to the cancel element. (type `HTMLAttributes`; optional)
- `closeProps`: Properties forwarded to the close element. (type `HTMLAttributes`; optional)

### Imperative `toast` methods

| Method                                                                      | Description                                           |
| --------------------------------------------------------------------------- | ----------------------------------------------------- |
| `toast(message, data?)`                                                     | Show a `default` toast; returns the toast id.         |
| `toast.success/error/warning/info/loading(message, data?)`                  | Show a typed toast.                                   |
| `toast.custom(component, data?)`                                            | Show a fully custom VNode.                            |
| `toast.promise(promise, { loading, success, error, description, finally })` | Bind a promise lifecycle to a toast.                  |
| `toast.dismiss(id?)`                                                        | Dismiss one toast, or all toasts when no id is given. |
| `toast.getHistory()`                                                        | Read all created toasts.                              |
| `toast.getToasts()`                                                         | Read the currently active (non-dismissed) toasts.     |

Common `data` options: `description`, `position`, `duration`, `action`/`cancel` (+ `onAction`/`onCancel`), `icon`, `richColor`, `inverted`, `showClose`, `dismissible`, `toasterId`, `id`, `ui`.

## Notes

### Architecture and benchmark differences

`Toaster` is a self-contained state owner that subscribes to a module-level `ToastState` observer and drives stacking/expansion, swipe, focus management and the auto-close timers, while `SToastProvider` only injects the recipe classes and the animation stylesheet. This is an imperative-first model like Ant Design's `message`/`notification`, Element Plus `ElMessage`, Mantine `notifications` and Naive UI `useMessage` — unlike shadcn/ui which has no global toast primitive. SoybeanUI distinguishes itself with stacked/expandable toasts, swipe-to-dismiss, promise toasts, and a focus hotkey, matching the ergonomics of Sonner while keeping a headless/styled split.

| Capability                  | SoybeanUI | shadcn/ui | Ant Design message | Element Plus ElMessage | Mantine notifications | Naive UI useMessage |
| :-------------------------- | :-------: | :-------: | :----------------: | :--------------------: | :-------------------: | :-----------------: |
| Imperative API              |    ✅     |     —     |         ✅         |           ✅           |          ✅           |         ✅          |
| Types (success/error/…)     |    ✅     |     —     |         ✅         |           ✅           |          ✅           |         ✅          |
| Positions (6)               |    ✅     |     —     |         ✅         |           ✅           |          ✅           |         ✅          |
| Stack / expand              |    ✅     |     —     |         —          |           —            |          ✅           |          —          |
| Swipe to dismiss            |    ✅     |     —     |         —          |           —            |           —           |          —          |
| Promise toasts              |    ✅     |     —     |         ✅         |           —            |          ✅           |         ✅          |
| Rich color / inverted       |    ✅     |     —     |         ✅         |           —            |           —           |          —          |
| Pause on hover / hidden tab |    ✅     |     —     |         ✅         |           ✅           |          ✅           |         ✅          |
| Focus hotkey                |    ✅     |     —     |         —          |           —            |           —           |          —          |

`—` = unsupported or a different interaction model.

### Cautions

- A mounted `SToastProvider` is required to render toasts; `SConfigProvider` mounts one automatically (unless `customToast`).
- `duration` of `0` or `Infinity` disables auto-dismiss; the timer pauses while the toast is hovered, expanded, or the tab is hidden.
- `visibleCounts` (default `3`) limits visible toasts per position; older toasts stack behind and expand on hover when `defaultExpanded`.
- Toasts are swipe-dismissible by default; set `dismissible: false` to disable (e.g. for `loading`).
- The viewport region is `aria-live="polite"`; the default hotkey `Alt+T` focuses the toast list. Override `hotkey`/`containerAriaLabel` as needed.

### Roadmap

No blocking gaps identified for the core toast API.

## FAQ

### How do I show a basic toast?

```ts
import { toast } from '@soybeanjs/ui';

toast('Changes saved');
```

### How do I show a typed toast?

```ts
toast.success('All good');
toast.error('Something went wrong');
toast.loading('Uploading…');
```

### How do I show a promise toast?

```ts
toast.promise(fetchData(), {
  loading: 'Loading…',
  success: data => `Loaded ${data.length} items`,
  error: 'Failed to load'
});
```

### How do I change the position or duration?

Pass `data` options to the call (or set provider defaults):

```ts
toast('Bottom left', { position: 'bottom-left', duration: 5000 });
```

### How do I keep a toast from auto-dismissing?

Set `duration: Infinity`:

```ts
toast('Stays until dismissed', { duration: Infinity });
```

### How do I render custom content?

Use `toast.custom` with a VNode, or the `custom` option:

```ts
toast.custom(h(VNode));
```

## Toggle

- Page URL: /components/toggle
- Markdown URL: /components/toggle.md
- Description: A two-state button that toggles between pressed (on) and unpressed (off) states, reflecting its state via aria-pressed and data-state. Use it for an immediate, exclusive on/off switch such as a formatting tool or a filter chip; when the choice belongs to a form that needs explicit submission, prefer SCheckbox instead.

# Toggle

## Overview

A two-state button that toggles between pressed (`on`) and unpressed (`off`) states, reflecting its state via `aria-pressed` and `data-state`. Use it for an immediate, exclusive on/off switch such as a formatting tool or a filter chip; when the choice belongs to a form that needs explicit submission, prefer `SCheckbox` instead.

## Usage

Usage examples for toggle are rendered on the site.

## Features

- 🎚 `modelValue` / `defaultValue` — controlled and uncontrolled modes backed by `useControllableState`
- ♿ `aria-pressed` + `data-state` (`on`/`off`) dual reflection, axe-clean
- ⌨️ Keyboard operable — Enter and Space toggle via native button behavior
- 🎨 3 variants (outline/soft/ghost) × 6 sizes × 8 colors × 4 shapes via `toggleVariants`
- 🧩 Full `SButton` prop surface (icon slots, `asChild`, loading via button props) through headless `Toggle`
- 📦 Slot props expose `modelValue` / `pressed` / `state` / `disabled` for custom content
- 🚫 Disabled state with `disabled` + `aria-disabled` and guarded click handling

## Demos

Interactive demos for toggle are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (1): Toggle.

### Toggle

#### Props
Properties for the Toggle component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ToggleVariant`; optional)
- `shape`: Shape of the component. (type `ToggleShape`; optional)
- `defaultValue`: The pressed state of the toggle when it is initially rendered. (type `boolean`; optional)
- `modelValue`: The controlled pressed state of the toggle. Can be bound with v-model. (type `boolean`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the Toggle component.
- `update:modelValue`: Event handler called when the pressed state changes. (type `[value: boolean]`; parameters `value: boolean`)

## Notes

### Architecture and benchmark differences

SoybeanUI builds the toggle from the headless `Toggle` (`useControllableState` + `Button` base + `aria-pressed`/`data-state` reflection + disabled-guarded click) and a thin UI wrapper `SToggle` that only computes `toggleVariants` classes and forwards `update:modelValue`. The `data-state` attribute drives the pressed styling through UnoCSS `data-[state=on]:*` selectors, keeping state and visuals decoupled. `toggle` is a Radix/shadcn-native pattern; the other benchmark libraries express the same interaction through button-plus-state or segmented controls.

| Capability                    | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn `Toggle` |
| :---------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :-------------: |
| headless/styled split         |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| Pressed/unpressed state       |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| Controlled/uncontrolled       |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| `aria-pressed` + `data-state` |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| Variants (outline/soft/ghost) |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| Sizes/shapes (6 sizes × 4)    |    ✅     |     —      |      —       |    —    |    —     |        —        |
| Keyboard (Enter/Space)        |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| Disabled                      |    ✅     |     —      |      —       |    —    |    —     |       ✅        |
| Axe-clean                     |    ✅     |     —      |      —       |    —    |    —     |        —        |
| Pressed-state icon animation  |    ➕     |     ✅     |      —       |    —    |    —     |        —        |

### Cautions

- An icon-only toggle has no accessible name — pass `aria-label` (or use a visible label) to stay axe-clean.
- The pressed state is reflected by `aria-pressed` and `data-state`; style the pressed look with `data-[state=on]:*` utilities or the built-in variants.
- Enter/Space toggling relies on the native button behavior of the `Button` base.
- For exclusive multi-choice, compose toggles with `SToggleGroup` instead of managing state by hand.

## FAQ

### Controlled or uncontrolled?

Pass `modelValue` with `v-model` for a controlled value, or `defaultValue` to let the toggle own its state internally. Both are supported via `useControllableState`.

### How do I build an icon-only toggle?

Put an icon in the default slot and add `aria-label` (e.g. `aria-label="Bold"`). The `toggleVariants` base already neutralizes `svg` pointer events and gives icons a default `size-4`.

### What is the difference between `SToggle` and `SButton`?

`SToggle` is a stateful button — it remembers whether it is pressed and reflects that via `aria-pressed`/`data-state` with pressed styling; `SButton` is stateless and only emits clicks.

### How do I build a group of toggles?

Use `SToggleGroup` — it manages single/multiple selection and the associated `aria-pressed` state for you.

## ToggleGroup

- Page URL: /components/toggle-group
- Markdown URL: /components/toggle-group.md
- Description: A set of two-state buttons that can be toggled on or off as a group, supporting single and multiple selection. Use it for formatting toolbars, filter chips, or any exclusive (or multi-choice) segmented control where the selection changes immediately. For segmented _single_ options that must look like a unified control, SSegment may fit better; for a single independent on/off button, use SToggle.

# ToggleGroup

## Overview

A set of two-state buttons that can be toggled on or off as a group, supporting single and multiple selection. Use it for formatting toolbars, filter chips, or any exclusive (or multi-choice) segmented control where the selection changes immediately. For segmented _single_ options that must look like a unified control, `SSegment` may fit better; for a single independent on/off button, use `SToggle`.

## Usage

Usage examples for toggle-group are rendered on the site.

## Features

- 🎯 Single / multiple selection — `multiple` switches between one and many selected items, with a type-safe generic value (`M extends boolean`, `T extends DefinedValue`)
- 🎚 Controlled / uncontrolled — `v-model` and `defaultValue` (scalar or array) backed by `useControllableState`
- ⌨️ Roving focus keyboard navigation — arrow keys move focus between items, `loop` wraps around, and arrow direction reverses in RTL
- ♿ `aria-pressed` + `data-state` (`on`/`off`) dual reflection, axe-clean
- 🎨 3 variants (outline/soft/ghost) × 6 sizes × 8 colors × 2 orientations via `toggleGroupVariants`
- 🧩 Per-item full `Button` prop surface (`as`/`asChild`, `type`, item-level `disabled`), and slot props exposing `pressed` / `disabled`
- 📝 Form integration — `name`/`required` render a hidden input so the selection submits with the owning form
- 🧩 `ui` per-slot class overrides (`root` / `item`)

## Component family

- `SToggleGroup` — the group root that manages selection state, orientation, and roving focus
- `SToggleGroupItem` — an individual toggleable button; pass a unique `value` that identifies it in the group

## Demos

Interactive demos for toggle-group are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (3): ToggleGroup, ToggleGroupItem, ToggleGroupRoot.

### ToggleGroup

#### Props
Properties for the ToggleGroup component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `color`: Theme color of the component. (type `ThemeColor`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `variant`: Visual variant of the component. (type `ToggleGroupVariant`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ToggleGroupUi>`; optional)
- `rovingFocus`: When `false`, navigating through items with arrow keys is disabled. (type `boolean`; optional)
- `disabled`: When `true`, prevents interaction with all items in the group. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation loops from last to first item, and vice versa. (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? T[] : T)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? T[] : T)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ToggleGroup component.
- `update:modelValue`: No description. (type `[value: M extends true ? T[] : T]`; parameters `value: M extends true ? T[] : T`)

### ToggleGroupItem

#### Props
Properties for the ToggleGroupItem component.
- `value`: A unique value that identifies the item inside the group. (type `T`; required)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ToggleGroupRoot

#### Props
Properties for the ToggleGroupRoot component.
- `rovingFocus`: When `false`, navigating through items with arrow keys is disabled. (type `boolean`; optional)
- `disabled`: When `true`, prevents interaction with all items in the group. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation loops from last to first item, and vice versa. (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? T[] : T)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? T[] : T)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ToggleGroupRoot component.
- `update:modelValue`: No description. (type `[value: M extends true ? T[] : T]`; parameters `value: M extends true ? T[] : T`)

## Notes

### Architecture and benchmark differences

SoybeanUI builds the group from headless `ToggleGroupRoot` (`useSelection` + `useRovingFocusGroup` + hidden-input form proxy) and `ToggleGroupItem` (dynamically backed by `useRovingFocusGroupItem` or the `Button` base depending on `rovingFocus`). The UI wrapper `SToggleGroup` is a thin pass-through that only computes `toggleGroupVariants` classes; `data-state` drives the pressed look through UnoCSS `data-[state=on]:*` selectors. `toggle-group` is a Radix/shadcn-native pattern; the other benchmark libraries express the same interaction with radio/button groups or segmented controls.

| Capability                        | SoybeanUI | Ant Design | Element Plus | Mantine | Naive UI | shadcn `ToggleGroup` |
| :-------------------------------- | :-------: | :--------: | :----------: | :-----: | :------: | :------------------: |
| headless/styled split             |    ✅     |     —      |      —       |    —    |    —     |          ✅          |
| Single / multiple selection       |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |          ✅          |
| Controlled / uncontrolled         |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |          ✅          |
| Roving focus arrow keys           |    ✅     |     —      |      —       |    —    |    —     |          ✅          |
| Loop navigation                   |    ✅     |     —      |      —       |    —    |    —     |          ✅          |
| RTL-aware arrow direction         |    ✅     |     —      |      —       |    —    |    —     |          ✅          |
| `aria-pressed` + `data-state`     |    ✅     |     —      |      —       |    —    |    —     |          ✅          |
| Orientation (horizontal/vertical) |    ✅     |     —      |      ✅      |   ✅    |    —     |          ✅          |
| Variants × sizes × colors         |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |          —           |
| Hidden-input form submission      |    ✅     |     —      |      —       |    —    |    —     |          —           |
| Clearable single deselect         |    ✅     |     ✅     |      —       |    —    |    —     |          —           |
| Disabled (group + item)           |    ✅     |     ✅     |      ✅      |   ✅    |    ✅    |          ✅          |

### Cautions

- `rovingFocus`, `loop`, and `clearable` default to `true`. Disabling `rovingFocus` falls back to a plain `role="group"` with no arrow-key navigation.
- Group-level `disabled` disables every item; item-level `disabled` only affects that item, and the two are combined (`group || item`).
- In single mode, clicking the selected item again emits `update:modelValue` with `undefined` (unless `:clearable="false"`) — handle the `undefined` value in the parent.
- Form submission requires `name`; `required` only marks the hidden input, it does not validate.
- For icon-only items, add `aria-label` so the button has an accessible name.
- In a `form`, the hidden input is only rendered when the group is a form control and `name` is set.

## FAQ

### Single or multiple selection?

Single is the default. Pass `multiple` to allow several items at once — `modelValue`/`defaultValue` then become arrays and the generic `M` is inferred from them.

### How do I allow deselecting the selected item in single mode?

`clearable` defaults to `true`, so clicking the active item clears it and emits `undefined`. Set `:clearable="false"` to keep a selection always present.

### How do I make arrow keys wrap around?

Keep `loop` (default `true`) and the focus wraps from the last to the first item and vice versa. Disabled items are skipped.

### What is the difference between `SToggleGroup` and `SToggle`?

`SToggleGroup` coordinates a set of items: it owns single/multiple selection, roving-focus keyboard navigation, and shared `aria-pressed` state. `SToggle` is a single standalone toggle with no group coordination.

### How do I render the group vertically?

Set `orientation="vertical"` — the layout switches to a stacked column and arrow navigation follows the vertical axis.

## Toolbar

- Page URL: /components/toolbar
- Markdown URL: /components/toolbar.md
- Description: A compact container that groups related actions, links, and toggle controls into a single roving-focus toolbar. SToolbar combines the headless toolbar primitives (ToolbarRoot/ToolbarButton/ToolbarLink/ToolbarSeparator/ToolbarToggleGroup/ToolbarToggleItem) with the toolbarVariants style recipe (7 slots, 6 sizes × 2 orientations).

# Toolbar

## Overview

A compact container that groups related actions, links, and toggle controls into a single roving-focus toolbar. `SToolbar` combines the headless toolbar primitives (`ToolbarRoot`/`ToolbarButton`/`ToolbarLink`/`ToolbarSeparator`/`ToolbarToggleGroup`/`ToolbarToggleItem`) with the `toolbarVariants` style recipe (7 slots, 6 sizes × 2 orientations).

Use a toolbar for a dense, keyboard-navigable row of actions. For a single action button use `button`; for grouped buttons use `toggle-group`.

## Usage

Usage examples for toolbar are rendered on the site.

## Features

- 🧩 Headless/styled split — `ToolbarRoot` provides the toolbar context; each part (`button`/`link`/`separator`/`toggle-group`) is a thin styled primitive
- ⌨️ Roving focus — arrow-key navigation between toolbar items, Home/End, with optional `loop`; separators/disabled items are skipped
- ↔️ Orientation — `horizontal` (default) or `vertical`; separators auto-flip orientation
- 🔘 Toggle group — `SToolbarToggleGroup`/`SToolbarToggleItem` for single/multi-select toggles with `v-model`
- 🔗 Link support — `SToolbarLink` renders an anchor with a leading icon (`showIcon`)
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ♿ Accessible — `role="toolbar"`, `aria-orientation`, `aria-pressed` on toggles, `axe-core` clean

## Component family

- `SToolbar` (styled) — the root wrapper; `toolbarVariants` recipe (`size` + orientation) with `provideToolbarUi`
- `SToolbarButton` (styled) — a toolbar button (`Button` base)
- `SToolbarLink` (styled) — a toolbar link (`Link` base with optional `showIcon`)
- `SToolbarSeparator` (styled) — an orientation-aware divider (`SeparatorRoot` base)
- `SToolbarToggleGroup` / `SToolbarToggleItem` (styled) — toggle-group controls (`ToggleGroupRoot`/`ToggleGroupItem` base)
- `ToolbarRoot`/`ToolbarButton`/`ToolbarLink`/`ToolbarSeparator`/`ToolbarToggleGroup`/`ToolbarToggleItem` (headless) — the underlying primitives

## Demos

Interactive demos for toolbar are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (7): Toolbar, ToolbarButton, ToolbarLink, ToolbarRoot, ToolbarSeparator, ToolbarToggleGroup, ToolbarToggleItem.

### Toolbar

#### Props
Properties for the Toolbar component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<ToolbarUi>`; optional)
- `orientation`: The orientation of the toolbar. (type `DataOrientation`; optional)
- `dir`: The reading direction of the toolbar. (type `Direction`; optional)
- `loop`: Whether keyboard roving focus loops. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ToolbarButton

#### Props
Properties for the ToolbarButton component.
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ToolbarButton component.
- `click`: Emitted when click occurs. (type `[event: PointerEvent]`; parameters `event: PointerEvent`)

### ToolbarLink

#### Props
Properties for the ToolbarLink component.
- `showIcon`: Whether or not to show an icon when the `href` prop is provided. (type `boolean`; optional)
- `to`: Route Location the link should navigate to when clicked on. (type `string | import("vue-router").RouteLocationAsRelativeGeneric | import("vue-router").RouteLocationAsPathGeneric`; optional)
- `replace`: Calls `router.replace` instead of `router.push`. (type `boolean`; optional)
- `href`: The URL the link should navigate to when clicked on. (type `string`; optional)
- `disabled`: When `true`, the link is disabled. (type `boolean`; optional)
- `activeClass`: Class to apply when the link is active (type `string`; optional)
- `exactActiveClass`: Class to apply when the link is exact active (type `string`; optional)
- `inactiveClass`: The class to apply to the link when it is inactive. (type `string`; optional)
- `prefetchedClass`: A class to apply to links that have been prefetched. (type `string`; optional)
- `external`: Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases (type `boolean`; optional)
- `ariaCurrentValue`: Value passed to the attribute `aria-current` when the link is exact active. (type `'true' | 'false' | 'page' | 'date' | 'time' | 'step' | 'location'`; default ``'page'``; optional)
- `viewTransition`: Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported. (type `boolean`; optional)
- `target`: Where to display the linked URL, as the name for a browsing context. (type `(string & {}) | '_blank' | '_parent' | '_self' | '_top' | null`; optional)
- `rel`: A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links. (type `(string & {}) | 'noopener' | 'noreferrer' | 'nofollow' | 'sponsored' | 'ugc' | null`; default `'noopener noreferrer'`; optional)
- `noRel`: If set to true, no rel attribute will be added to the link (type `boolean`; optional)
- `prefetch`: When enabled will prefetch middleware, layouts and payloads of links in the viewport. (type `boolean`; optional)
- `prefetchOn`: Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility. (type `'visibility' | 'interaction' | Partial<{ visibility: boolean; interaction: boolean; }>`; optional)
- `noPrefetch`: Escape hatch to disable `prefetch` attribute. (type `boolean`; optional)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href` for this specific link. Overrides the global `trailingSlash` option if provided. (type `'append' | 'remove'`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ToolbarRoot

#### Props
Properties for the ToolbarRoot component.
- `orientation`: The orientation of the toolbar. (type `DataOrientation`; optional)
- `dir`: The reading direction of the toolbar. (type `Direction`; optional)
- `loop`: Whether keyboard roving focus loops. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### ToolbarSeparator

#### Props
Properties for the ToolbarSeparator component.
- `decorative`: Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes are updated so that that the rendered element is removed from the accessibility tree. (type `boolean`; optional)

### ToolbarToggleGroup

#### Props
Properties for the ToolbarToggleGroup component.
- `rovingFocus`: When `false`, navigating through items with arrow keys is disabled. (type `boolean`; optional)
- `disabled`: When `true`, prevents interaction with all items in the group. (type `boolean`; optional)
- `orientation`: The orientation of the component. (type `DataOrientation`; optional)
- `dir`: The reading direction of the group when applicable. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation loops from last to first item, and vice versa. (type `boolean`; optional)
- `modelValue`: The controlled value of the selected item(s). Use this when you need to control the state of the items. Can be bound with `v-model` (type `(M extends true ? T[] : T)`; optional)
- `defaultValue`: The default value of the selected item(s). Use this when you need to set the initial state of the items. (type `(M extends true ? T[] : T)`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`. (type `M`; optional)
- `clearable`: Whether selected item can be cleared when `multiple` is false. (type `boolean`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `SelectionBehavior`; default `'toggle'`; optional)
- `name`: The name of the field. Submitted with its owning form as part of a name/value pair. (type `string`; optional)
- `required`: When `true`, indicates that the user must set the value before the owning form can be submitted. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the ToolbarToggleGroup component.
- `update:modelValue`: No description. (type `[value: M extends true ? T[] : T]`; parameters `value: M extends true ? T[] : T`)

### ToolbarToggleItem

#### Props
Properties for the ToolbarToggleItem component.
- `value`: A unique value that identifies the item inside the group. (type `T`; required)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

The toolbar family is a multi-slot composition: `ToolbarRoot` provides the roving-focus + orientation context while each part (button/link/separator/toggle-group) reuses the button, link, separator and toggle-group primitives, with the UI wrapper injecting `toolbarVariants` classes per slot. This mirrors radix-ui/shadcn-ui's headless toolbar/toggle-group split. Ant Design, Element Plus, Mantine and Naive UI ship a button/segmented-control but not a dedicated roving-focus toolbar container with orientation-aware separators; SoybeanUI provides a complete toolbar with `loop`/RTL support and a `size` scale.

| Capability            | SoybeanUI | shadcn/ui | Ant Design | Element Plus | Mantine | Naive UI |
| :-------------------- | :-------: | :-------: | :--------: | :----------: | :-----: | :------: |
| Headless/styled split |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Roving focus + loop   |    ✅     |    ✅     |     —      |      —       |   ✅    |    —     |
| Orientation-aware     |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Toggle group          |    ✅     |    ✅     |     ✅     |      ✅      |   ✅    |    —     |
| Link support          |    ✅     |    ✅     |     —      |      —       |    —    |    —     |
| Sizes (6)             |    ✅     |     —     |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- `SToolbar` renders `role="toolbar"` with `aria-orientation` (`horizontal` default / `vertical`); separators auto-flip to match.
- Roving focus uses arrow keys + Home/End; `loop` wraps navigation. Disabled items and separators are skipped.
- `SToolbarToggleGroup` supports single (`model-value` string) and multiple (`model-value` array) selection with `v-model`.
- `dir`/RTL is derived from the `ConfigProvider` locale (e.g. `ar`) or set explicitly on the root.
- `SToolbarLink` renders an anchor; `showIcon` adds a leading icon next to the link text.

### Roadmap

N/A — toolbar is feature-complete for the current parity set.

## FAQ

### How do I build a toolbar?

Compose buttons, links, a separator and a toggle group:

```vue

  <SToolbarButton>Cut</SToolbarButton>
  <SToolbarButton>Copy</SToolbarButton>
  <SToolbarSeparator />
  <SToolbarToggleGroup v-model="align">
    <SToolbarToggleItem value="left">Left</SToolbarToggleItem>
    <SToolbarToggleItem value="center">Center</SToolbarToggleItem>
  </SToolbarToggleGroup>

```

### How do I make it vertical?

Set `orientation="vertical"`:

```vue

  <SToolbarButton>Up</SToolbarButton>
  <SToolbarButton>Down</SToolbarButton>

```

### How do I make navigation loop?

Set `loop`:

```vue

  <SToolbarButton>A</SToolbarButton>
  <SToolbarButton>B</SToolbarButton>

```

### How do I add a link?

Use `SToolbarLink` with `href` and `show-icon`:

```vue

  <SToolbarLink href="https://example.com" show-icon>Website</SToolbarLink>

```

## Tooltip

- Page URL: /components/tooltip
- Markdown URL: /components/tooltip.md
- Description: A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. STooltip combines the headless TooltipRoot/TooltipTrigger/TooltipPositioner/TooltipPopup/TooltipArrow primitive family (built on the shared Popper) with the tooltipVariants style recipe (3 slots, 6 sizes).

# Tooltip

## Overview

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. `STooltip` combines the headless `TooltipRoot`/`TooltipTrigger`/`TooltipPositioner`/`TooltipPopup`/`TooltipArrow` primitive family (built on the shared `Popper`) with the `tooltipVariants` style recipe (3 slots, 6 sizes).

Use a tooltip for a short, non-interactive hint. For rich hover content use `hover-card`; for click-triggered content use `popover`; for a confirmation use `popconfirm`.

## Usage

Usage examples for tooltip are rendered on the site.

## Features

- 🧩 Headless/styled split — `TooltipCompact` aggregates the popper trigger, positioner, popup and arrow; `STooltip` only injects styles and forwards slots/events
- 🖱️ Hover + focus — opens on pointer hover or keyboard focus; dismisses on Escape or pointer leave
- ⏱️ Delay tuning — `delayDuration` (open) and `skipDelayDuration` (between triggers), with global defaults via `ConfigProvider`
- 🎯 Placement — full popper `placement` control with collision avoidance and side-aware slide animations
- 🔽 Arrow — `showArrow` renders a positioned arrow; configurable via `arrowProps`
- 🏷️ Content — `content` prop or the default slot
- ♿ Behavior toggles — `ignoreNonKeyboardFocus`, `disableHoverableContent`, `disableClosingTrigger`, `disabled`
- 📐 6 sizes — xs–2xl `size`; per-slot `ui` overrides
- ♿ Accessible — `role="tooltip"` (visually-hidden text node), non-modal, `axe-core` zero violations open and closed

## Component family

- `STooltip` (styled) — the entry wrapper; `tooltipVariants` recipe with dynamic slot forwarding
- `TooltipRoot` (headless) — the state owner; `open` via `useControllableState`, `delayDuration`/`skipDelayDuration`/`disabled`/`ignoreNonKeyboardFocus`, merges the global `ConfigProvider` tooltip config
- `TooltipTrigger` (headless) — the anchor that opens the tooltip on hover/focus
- `TooltipPositioner` / `TooltipPositionerImpl` (headless) — the positioned surface (built on `PopperPositioner`)
- `TooltipPopup` (headless) — the popup body; exposes a visually-hidden `role="tooltip"` text node for screen readers
- `TooltipArrow` (headless) — the popper arrow
- `TooltipCompact` (headless) — the aggregated composite; composes trigger/positioner/popup/arrow and exposes the slots

## Demos

Interactive demos for tooltip are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (9): Tooltip, TooltipArrow, TooltipCompact, TooltipPopup, TooltipPortal, TooltipPositioner, TooltipProvider, TooltipRoot, TooltipTrigger.

### Tooltip

#### Props
Properties for the Tooltip component.
- `class`: class of popup (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TooltipUi>`; optional)
- `content`: Content. (type `string`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopperAnchorProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `TooltipPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `TooltipPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `TooltipPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `TooltipArrowProps`; optional)
- `defaultOpen`: The open state of the tooltip when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the tooltip. (type `boolean`; optional)
- `dir`: No description. (type `Direction`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: When `true`, disable tooltip (type `boolean`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the tooltip gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableHoverableContent`: When `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. (type `boolean`; default `false`; optional)
- `disableClosingTrigger`: When `true`, clicking on trigger will not close the content. (type `boolean`; default `false`; optional)
- `ignoreNonKeyboardFocus`: Prevent the tooltip from opening if the focus did not come from the keyboard by matching against the `:focus-visible` selector. This is useful if you want to avoid opening it when switching browser tabs or closing a dialog. (type `boolean`; default `false`; optional)
#### Emits
Events for the Tooltip component.
- `update:open`: Event handler called when the open state of the tooltip changes. (type `[value: boolean, reason?: PopperOpenChangeReason | undefined]`; parameters `value: boolean, reason?: PopperOpenChangeReason | undefined`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
#### Slots
Slots for the Tooltip component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `(() => any) | undefined`)

### TooltipArrow

- No documented props, emits, slots, or slot props were available.

### TooltipCompact

#### Props
Properties for the TooltipCompact component.
- `content`: Content. (type `string`; optional)
- `placement`: Placement. (type `Placement`; optional)
- `showArrow`: Whether to show an arrow. (type `boolean`; optional)
- `triggerProps`: Properties forwarded to the trigger element. (type `PopperAnchorProps`; optional)
- `portalProps`: Properties forwarded to the portal element. (type `TooltipPortalProps`; optional)
- `positionerProps`: Properties forwarded to the positioner element. (type `TooltipPositionerProps`; optional)
- `popupProps`: Properties forwarded to the popup element. (type `TooltipPopupProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element. (type `TooltipArrowProps`; optional)
- `defaultOpen`: The open state of the tooltip when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the tooltip. (type `boolean`; optional)
- `dir`: No description. (type `Direction`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: When `true`, disable tooltip (type `boolean`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the tooltip gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableHoverableContent`: When `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. (type `boolean`; default `false`; optional)
- `disableClosingTrigger`: When `true`, clicking on trigger will not close the content. (type `boolean`; default `false`; optional)
- `ignoreNonKeyboardFocus`: Prevent the tooltip from opening if the focus did not come from the keyboard by matching against the `:focus-visible` selector. This is useful if you want to avoid opening it when switching browser tabs or closing a dialog. (type `boolean`; default `false`; optional)
#### Emits
Events for the TooltipCompact component.
- `update:open`: Event handler called when the open state of the tooltip changes. (type `[value: boolean, reason?: PopperOpenChangeReason | undefined]`; parameters `value: boolean, reason?: PopperOpenChangeReason | undefined`)
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)
#### Slots
Slots for the TooltipCompact component.
- `default`: Custom content for the default slot. (type `(() => any) | undefined`)
- `trigger`: Custom content for the trigger slot. (type `(() => any) | undefined`)

### TooltipPopup

#### Props
Properties for the TooltipPopup component.
- `ariaLabel`: By default, screen readers will announce the content inside the component. If this is not descriptive enough, or you have content that cannot be announced, use `aria-label` as a more descriptive label. (type `string`; optional)

### TooltipPortal

- No documented props, emits, slots, or slot props were available.

### TooltipPositioner

#### Props
Properties for the TooltipPositioner component.
- `placement`: The placement of the floating element. If used, it will override the `side` and `align` props. (type `Placement`; default `undefined`; optional)
- `side`: The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. (type `Side`; default `'bottom'`; optional)
- `sideOffset`: The distance in pixels from the trigger. (type `number`; default `0`; optional)
- `sideFlip`: Flip to the opposite side when colliding with boundary. (type `boolean`; default `true`; optional)
- `align`: The preferred alignment against the trigger. May change when collisions occur. (type `Align`; default `'center'`; optional)
- `alignOffset`: An offset in pixels from the `start` or `end` alignment options. (type `number`; default `0`; optional)
- `alignFlip`: Flip alignment when colliding with boundary. May only occur when `prioritizePosition` is true. (type `boolean`; default `true`; optional)
- `avoidCollisions`: When `true`, overrides the side and align preferences to prevent collisions with boundary edges. (type `boolean`; default `true`; optional)
- `collisionBoundary`: The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. (type `Element | (Element | null)[] | null`; default `[ ]`; optional)
- `collisionPadding`: The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: { top: 20, left: 20 }. (type `Padding`; default `0`; optional)
- `arrowPadding`: The padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. (type `number`; default `0`; optional)
- `hideShiftedArrow`: When `true`, hides the arrow when it cannot be centered to the reference element. (type `boolean`; default `true`; optional)
- `sticky`: The sticky behavior on the align axis. `partial` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst "always" will keep the content in the boundary regardless. (type `'partial' | 'always'`; default `'partial'`; optional)
- `hideWhenDetached`: Whether to hide the content when the trigger becomes fully occluded. (type `boolean`; default `false`; optional)
- `positionStrategy`: The type of CSS position property to use. (type `'fixed' | 'absolute'`; default `'fixed'`; optional)
- `updatePositionStrategy`: Strategy to update the position of the floating element on every animation frame. (type `'always' | 'optimized'`; default `'optimized'`; optional)
- `disableUpdateOnLayoutShift`: Whether to disable the update position for the content when the layout shifted. (type `boolean`; default `false`; optional)
- `prioritizePosition`: Force content to be position within the viewport. Might overlap the reference element, which may not be desired. (type `boolean`; default `false`; optional)
- `reference`: The custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. (type `ReferenceElement`; optional)
- `trapFocus`: Whether focus is trapped inside the popup while open (Tab cycles within the layer and body scroll is locked for modal layers). (type `boolean`; default `modal`; optional)
- `disableHoverableContent`: When `true`, hovering the popup closes instead of keeping it open (the grace area is disabled, so leaving the trigger closes the layer immediately). (type `boolean`; default `false`; optional)
- `onGracePointerExit`: Callback invoked when the pointer finally leaves the grace area. Lets an upper layer (e.g. Tooltip) run area-scoped close logic without registering its own second grace area. (type `(() => void)`; optional)
- `forceMount`: Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. (type `boolean`; optional)
#### Emits
Events for the TooltipPositioner component.
- `escapeKeyDown`: Event handler called when the escape key is down. Can be prevented. (type `[event: KeyboardEvent]`; parameters `event: KeyboardEvent`)
- `pointerDownOutside`: Event handler called when a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented. (type `[event: PointerDownOutsideEvent]`; parameters `event: PointerDownOutsideEvent`)
- `focusOutside`: Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented. (type `[event: FocusOutsideEvent]`; parameters `event: FocusOutsideEvent`)
- `interactOutside`: Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented. (type `[event: PointerDownOutsideEvent | FocusOutsideEvent]`; parameters `event: PointerDownOutsideEvent | FocusOutsideEvent`)
- `openAutoFocus`: Event handler called when auto-focusing on open. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `closeAutoFocus`: Event handler called when auto-focusing on close. Can be prevented. (type `[event: Event]`; parameters `event: Event`)
- `placed`: No description. (type `[]`)

### TooltipProvider

#### Props
Properties for the TooltipProvider component.
- `delayDuration`: The duration from when the pointer enters the trigger until the tooltip gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableHoverableContent`: When `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. (type `boolean`; default `false`; optional)
- `disableClosingTrigger`: When `true`, clicking on trigger will not close the content. (type `boolean`; default `false`; optional)
- `disabled`: When `true`, disable tooltip (type `boolean`; default `false`; optional)
- `ignoreNonKeyboardFocus`: Prevent the tooltip from opening if the focus did not come from the keyboard by matching against the `:focus-visible` selector. This is useful if you want to avoid opening it when switching browser tabs or closing a dialog. (type `boolean`; default `false`; optional)
- `positionerProps`: Props to be passed down to the positioner. Useful when you need to control the positioner, such as disabling it when the trigger is disabled. (type `TooltipPositionerProps`; optional)

### TooltipRoot

#### Props
Properties for the TooltipRoot component.
- `defaultOpen`: The open state of the tooltip when it is initially rendered. Use when you do not need to control its open state. (type `boolean`; optional)
- `open`: The controlled open state of the tooltip. (type `boolean`; optional)
- `dir`: No description. (type `Direction`; optional)
- `modal`: No description. (type `boolean`; optional)
- `disabled`: When `true`, disable tooltip (type `boolean`; optional)
- `delayDuration`: The duration from when the pointer enters the trigger until the tooltip gets opened. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another trigger without incurring a delay again. (type `number`; default `300`; optional)
- `disableHoverableContent`: When `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. (type `boolean`; default `false`; optional)
- `disableClosingTrigger`: When `true`, clicking on trigger will not close the content. (type `boolean`; default `false`; optional)
- `ignoreNonKeyboardFocus`: Prevent the tooltip from opening if the focus did not come from the keyboard by matching against the `:focus-visible` selector. This is useful if you want to avoid opening it when switching browser tabs or closing a dialog. (type `boolean`; default `false`; optional)
- `positionerProps`: Props to be passed down to the positioner. Useful when you need to control the positioner, such as disabling it when the trigger is disabled. (type `TooltipPositionerProps`; optional)
#### Emits
Events for the TooltipRoot component.
- `update:open`: Event handler called when the open state of the tooltip changes. (type `[value: boolean, reason?: PopperOpenChangeReason | undefined]`; parameters `value: boolean, reason?: PopperOpenChangeReason | undefined`)

### TooltipTrigger

- No documented props, emits, slots, or slot props were available.

## Notes

### Architecture and benchmark differences

`TooltipCompact` owns the trigger/positioner/popup/arrow composition while every primitive stays style-free and only the UI wrapper injects the `tooltipVariants` classes. This mirrors radix-ui/shadcn-ui's headless split, built on the shared `Popper` primitives. Ant Design, Element Plus, Mantine and Naive UI ship a single styled tooltip with `title`/`placement` props; SoybeanUI additionally exposes per-slot `*Props`, a `size` scale, an arrow toggle, a `delayDuration`/`skipDelayDuration` tuning model with `ConfigProvider` global defaults, and an accessible visually-hidden `role="tooltip"` node.

| Capability            | SoybeanUI | shadcn/ui | Ant Design Tooltip | Element Plus Tooltip | Mantine Tooltip | Naive UI Tooltip |
| :-------------------- | :-------: | :-------: | :----------------: | :------------------: | :-------------: | :--------------: |
| Headless/styled split |    ✅     |    ✅     |         —          |          —           |        —        |        —         |
| Popper placement (12) |    ✅     |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |
| Delay tuning          |    ✅     |    ✅     |         —          |          ✅          |       ✅        |        —         |
| Arrow                 |    ✅     |    ✅     |         —          |          —           |        —        |        —         |
| Sizes (6)             |    ✅     |     —     |         —          |          —           |        —        |        —         |
| Focus trigger         |    ✅     |    ✅     |         ✅         |          ✅          |       ✅        |        ✅        |

`—` = unsupported or a different interaction model.

### Cautions

- The tooltip opens on hover and keyboard focus; tune `delayDuration`/`skipDelayDuration` (or the `ConfigProvider` tooltip defaults) to reduce accidental triggers.
- `ignoreNonKeyboardFocus` (default) ignores non-keyboard focus (e.g. programmatic), matching native tooltip semantics.
- The popup is rendered through a `Portal` (teleported to `document.body`); position it inside a relatively-positioned ancestor only with `portalProps: { disabled: true }`.
- `showArrow` renders an arrow; `arrowProps` can override its position/classes.
- The tooltip is non-modal and does not trap focus; it dismisses on Escape or pointer leave.

### Roadmap

N/A — tooltip is feature-complete for the current parity set.

## FAQ

### How do I add a tooltip to an element?

Wrap the element in the `trigger` slot and set `content`:

```vue

  <template #trigger><SButton>Delete</SButton></template>

```

### How do I position the tooltip?

Use `placement`:

```vue

  <template #trigger><SButton>Copy</SButton></template>

```

### How do I adjust the open timing?

Set `delay-duration` (ms), with `skip-delay-duration` between triggers:

```vue

  <template #trigger><SButton>Save</SButton></template>

```

### How do I hide the arrow?

Set `show-arrow={false}`:

```vue

  <template #trigger><SButton>?</SButton></template>

```

## Tree

- Page URL: /components/tree
- Markdown URL: /components/tree.md
- Description: A component for displaying hierarchical tree data with selection and expand/collapse support. STree combines the headless TreeRoot family of base primitives (TreeRoot/TreeItem/TreeVirtualizerRoot/TreeVirtualizerItem, zero-style) with the TreeRoot context (controlled/uncontrolled selection and expansion, single/multiple selection, cascading selection, Roving Focus keyboard navigation); STreeVirtualizer layers virtualization on top to smoothly handle 1000+ nodes. Node content is fully customized through the item slot — icons, checkboxes, indentation, and connector lines are all injected by the consumer.

# Tree

## Overview

A component for displaying hierarchical tree data with selection and expand/collapse support. `STree` combines the headless `TreeRoot` family of base primitives (`TreeRoot`/`TreeItem`/`TreeVirtualizerRoot`/`TreeVirtualizerItem`, zero-style) with the `TreeRoot` context (controlled/uncontrolled selection and expansion, single/multiple selection, cascading selection, Roving Focus keyboard navigation); `STreeVirtualizer` layers virtualization on top to smoothly handle 1000+ nodes. Node content is fully customized through the `item` slot — icons, checkboxes, indentation, and connector lines are all injected by the consumer.

## Usage

Usage examples for tree are rendered on the site.

## Features

- 🌳 Hierarchical data model — `items: TreeItemData<T>[]` (`value` plus optional recursive `children`); the `TreeItemData<T>` generic preserves custom field types
- 🎛️ Controlled/uncontrolled dual channels — `modelValue` / `defaultValue` control selection, `expanded` / `defaultExpanded` control expansion; both support `v-model` and `update:*` events
- ☑️ Single and multiple selection — `multiple` (linked to the `modelValue` type: single string ↔ array) toggles modes; `selectionBehavior: 'toggle' | 'replace'` controls multi-select clicks; `Shift + Arrow` performs contiguous range selection
- 🧩 Cascading selection — `propagateSelect` (selecting a parent cascades to descendants), `bubbleSelect` (a parent auto-selects when all children are selected), `allowParentSelect` (whether parent nodes can be selected directly)
- 📂 Expansion strategy — `toggleBehavior: 'multiple' | 'single'` (multiple expanded nodes by default; `single` collapses the previous node when expanding a new one, accordion-like)
- ⌨️ Keyboard navigation — Roving Focus: `↑/↓` move focus, `→/←` expand/collapse or enter/return to a parent level, `Enter`/`Space` select, character typeahead for quick location; `loop` (default `true`) wraps around; full RTL support
- ⚡ Virtualization — `STreeVirtualizer` + `height` renders only visible nodes, staying smooth with 1000+ nodes
- ♿ Accessibility — `role="tree"`/`treeitem` with `aria-expanded`/`aria-selected`/`aria-level`/`aria-setsize`/`aria-posinset`/`aria-multiselectable`/`aria-disabled`, plus `data-soybean-tree-*` data attributes

## Component family

- `STree` (styled) — entry wrapper; `TreeRootProps<T, U, M>` generic passthrough + `useForwardListeners` event merging + `top`/`item`/`bottom` slots; `withDefaults` mirrors the headless `loop: true` default
- `STreeVirtualizer` (styled) — virtualized wrapper; forwards `contentProps`/`dynamicContentProps` to `VirtualizerContent`; the `item` slot additionally exposes `virtualItem`
- `TreeRoot` (headless) — root component; `useControllableState` manages selection/expansion, `useSelectionBehavior` handles single/multi/range selection, `useRovingFocusGroup` + `useTypeahead` implement keyboard navigation; `provideTreeRootContext` bridges child items
- `TreeItem` (headless) — single node; `useRovingFocusGroupItem` manages focus, renders `aria-*` and `data-*` attributes, dispatches `select`/`toggle` events via `handleAndDispatchCustomEvent`
- `TreeVirtualizerRoot` (headless) — virtualized root; `VirtualizerRoot` + TanStack Virtual, forwards flattened `flattenItems`
- `TreeVirtualizerItem` (headless) — virtualized node; combines `TreeItem` + `VirtualizerItem` (`data-soybean-tree-virtualizer-item`)

## Demos

Interactive demos for tree are rendered on the site.

- 01 Basic — a basic directory tree (`items` + `default-expanded` + `top` slot)
- 02 Virtualizer — `STreeVirtualizer` rendering 1000+ nodes with virtualization

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (6): Tree, TreeItem, TreeRoot, TreeVirtualizer, TreeVirtualizerItem, TreeVirtualizerRoot.

### Tree

#### Slots
Slots for the Tree component.
- `top`: Content rendered before the tree items. (type `(() => any) | undefined`)
- `bottom`: Content rendered after the tree items. (type `(() => any) | undefined`)
- `item`: Content for a single tree item. (type `((props: { item: FlattenedItem<T>; modelValue: MaybeArray<string> | undefined; expanded: string[]; }) => any) | undef...`)

### TreeItem

#### Props
Properties for the TreeItem component.
- `value`: Value associated with the current item. (type `string`; required)
- `level`: Level. (type `number`; required)
- `disabled`: When `true`, prevents the user from selecting or toggling the item. (type `boolean`; optional)
- `disabledSelect`: When `true`, prevents the user from selecting the item. (type `boolean`; optional)
- `disabledToggle`: When `true`, prevents the user from toggling the item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the TreeItem component.
- `select`: Event handler called when selecting item. (type `[event: TreeSelectEvent<string>]`; parameters `event: TreeSelectEvent<string>`)
- `toggle`: Event handler called when toggling item. (type `[event: TreeToggleEvent<string>]`; parameters `event: TreeToggleEvent<string>`)

### TreeRoot

#### Props
Properties for the TreeRoot component.
- `modelValue`: The controlled value of the tree. Can be bound-with with `v-model`. (type `U`; optional)
- `defaultValue`: The value of the tree when initially rendered. Use when you do not need to control the state of the tree (type `U`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. (type `IsMultiple<U, M>`; optional)
- `items`: List of items (type `T[]`; optional)
- `expanded`: The controlled value of the expanded item. Can be bound-with with `v-model`. (type `string[]`; optional)
- `defaultExpanded`: The value of the expanded tree when initially rendered. (type `string[]`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `TreeSelectBehavior`; optional)
- `toggleBehavior`: Determines whether a "single" or "multiple" items can be toggled at a time. (type `TreeToggleBehavior`; default `'multiple'`; optional)
- `dir`: The reading direction. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with tree (type `boolean`; optional)
- `propagateSelect`: When `true`, selecting parent will select the descendants. (type `boolean`; optional)
- `bubbleSelect`: When `true`, selecting children will update the parent state. (type `boolean`; optional)
- `allowParentSelect`: When `true`, parent can be selected. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the TreeRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `update:expanded`: Emitted when the expanded state changes. (type `[value: string[]]`; parameters `value: string[]`)

### TreeVirtualizer

#### Props
Properties for the TreeVirtualizer component.
- `contentProps`: Properties forwarded to the content element. (type `VirtualizerContentProps`; optional)
- `dynamicContentProps`: Properties forwarded to the dynamic content element. (type `VirtualizerDynamicContentProps`; optional)
- `animated`: When `true`, renders visible items in normal document flow (dynamic mode) so item positions stay correct across expand/collapse without absolute offsets. (type `boolean`; default `false`; optional)
- `modelValue`: The controlled value of the tree. Can be bound-with with `v-model`. (type `U`; optional)
- `defaultValue`: The value of the tree when initially rendered. Use when you do not need to control the state of the tree (type `U`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. (type `IsMultiple<U, M>`; optional)
- `items`: List of items (type `T[]`; optional)
- `expanded`: The controlled value of the expanded item. Can be bound-with with `v-model`. (type `string[]`; optional)
- `defaultExpanded`: The value of the expanded tree when initially rendered. (type `string[]`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `TreeSelectBehavior`; optional)
- `toggleBehavior`: Determines whether a "single" or "multiple" items can be toggled at a time. (type `TreeToggleBehavior`; default `'multiple'`; optional)
- `dir`: The reading direction. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with tree (type `boolean`; optional)
- `propagateSelect`: When `true`, selecting parent will select the descendants. (type `boolean`; optional)
- `bubbleSelect`: When `true`, selecting children will update the parent state. (type `boolean`; optional)
- `allowParentSelect`: When `true`, parent can be selected. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `height`: The height of the virtualizer root (type `string | number`; required)
- `options`: Options. (type `VirtualizerOptions`; optional)
- `dynamic`: Whether dynamic. (type `boolean`; optional)
#### Emits
Events for the TreeVirtualizer component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `update:expanded`: Emitted when the expanded state changes. (type `[value: string[]]`; parameters `value: string[]`)

### TreeVirtualizerItem

#### Props
Properties for the TreeVirtualizerItem component.
- `value`: Value associated with the current item. (type `string`; required)
- `level`: Level. (type `number`; required)
- `disabled`: When `true`, prevents the user from selecting or toggling the item. (type `boolean`; optional)
- `disabledSelect`: When `true`, prevents the user from selecting the item. (type `boolean`; optional)
- `disabledToggle`: When `true`, prevents the user from toggling the item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `data`: Data. (type `VirtualItem`; required)
- `customStyle`: Whether custom style. (type `boolean`; optional)
#### Emits
Events for the TreeVirtualizerItem component.
- `select`: Event handler called when selecting item. (type `[event: TreeSelectEvent<string>]`; parameters `event: TreeSelectEvent<string>`)
- `toggle`: Event handler called when toggling item. (type `[event: TreeToggleEvent<string>]`; parameters `event: TreeToggleEvent<string>`)

### TreeVirtualizerRoot

#### Props
Properties for the TreeVirtualizerRoot component.
- `modelValue`: The controlled value of the tree. Can be bound-with with `v-model`. (type `U`; optional)
- `defaultValue`: The value of the tree when initially rendered. Use when you do not need to control the state of the tree (type `U`; optional)
- `multiple`: Determines whether a "single" or "multiple" items can be selected at a time. (type `IsMultiple<U, M>`; optional)
- `items`: List of items (type `T[]`; optional)
- `expanded`: The controlled value of the expanded item. Can be bound-with with `v-model`. (type `string[]`; optional)
- `defaultExpanded`: The value of the expanded tree when initially rendered. (type `string[]`; optional)
- `selectionBehavior`: How multiple selection should behave in the collection. (type `TreeSelectBehavior`; optional)
- `toggleBehavior`: Determines whether a "single" or "multiple" items can be toggled at a time. (type `TreeToggleBehavior`; default `'multiple'`; optional)
- `dir`: The reading direction. (type `Direction`; optional)
- `loop`: When `true`, keyboard navigation will loop from last item to first, and vice versa. (type `boolean`; default `true`; optional)
- `disabled`: When `true`, prevents the user from interacting with tree (type `boolean`; optional)
- `propagateSelect`: When `true`, selecting parent will select the descendants. (type `boolean`; optional)
- `bubbleSelect`: When `true`, selecting children will update the parent state. (type `boolean`; optional)
- `allowParentSelect`: When `true`, parent can be selected. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `height`: The height of the virtualizer root (type `string | number`; required)
- `options`: Options. (type `VirtualizerOptions`; optional)
- `dynamic`: Whether dynamic. (type `boolean`; optional)
#### Emits
Events for the TreeVirtualizerRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: M extends true ? string[] : string]`; parameters `value: M extends true ? string[] : string`)
- `update:expanded`: Emitted when the expanded state changes. (type `[value: string[]]`; parameters `value: string[]`)

## Notes

### Architecture and benchmark differences

`TreeRoot` owns all state (selection/expansion through the `useControllableState` controlled/uncontrolled dual channels) and the selection strategy (`useSelectionBehavior`'s toggle/replace/range selection); all base primitives stay zero-style. `STree`/`STreeVirtualizer` only mirror the `loop` default and pass through slots — the node visuals are fully composed inside the `item` slot via `STreeItem`/`STreeVirtualizerItem` (indentation, icons, checkboxes, focus states all injected through classes). Keyboard navigation builds on Roving Focus (`↑/↓` move, `→/←` expand/collapse, typeahead) and additionally supports `Shift` range selection — an interaction beyond the default contract of most mainstream tree components. Virtualization builds on the `@soybeanjs/headless` virtualizer and renders only visible nodes.

| Capability                                      | SoybeanUI | Ant Design | Element Plus | Naive UI |
| :---------------------------------------------- | :-------: | :--------: | :----------: | :------: |
| headless/style separation                       |    ✅     |     —      |      —       |    —     |
| Single/multiple selection (toggle/replace)      |    ✅     |     ✅     |      ✅      |    ✅    |
| Expansion strategy (single/multiple toggle)     |    ✅     |     ✅     |      ✅      |    ✅    |
| Cascading selection (propagate/bubble/parent)   |    ✅     |     ✅     |      ✅      |    ⚠️    |
| Keyboard navigation (arrows + loop + typeahead) |    ✅     |     ✅     |      ✅      |    ⚠️    |
| Virtualization (1k nodes)                       |    ✅     |     ✅     |      ⚠️      |    ✅    |
| Checkable mode (checkbox)                       |    ⚠️     |     ✅     |      ✅      |    ✅    |
| Draggable reordering                            |     —     |     ✅     |      ✅      |    ✅    |
| Async child loading (loadData)                  |     —     |     ✅     |      ✅      |    ✅    |
| Search filtering (searchValue)                  |     —     |     ✅     |      ✅      |    —     |

`⚠️` = partial support (SoybeanUI checkable can be built via `multiple` + a custom `item` slot checkbox icon + the `data-selected`/`data-contains-selected` states; Naive UI has no built-in range selection or character location).

### Cautions

- The `modelValue` type is tied to `multiple`: a single-string `modelValue` forces single-select; an array with `multiple` truthy enables multi-select (enforced by the `IsMultiple<U, M>` conditional type).
- The `item` slot is **free composition**: the consumer must render `STreeItem` (or `STreeVirtualizerItem`) passing `item.value`/`item.level`; the slot also exposes `item.data` (the raw node data) and `isExpanded`/`isSelected`/`isIndeterminate`/`hasChildren` states.
- Parent nodes are **not selectable by default** (`allowParentSelect` defaults to `false`); enable it explicitly when needed.
- `propagateSelect`/`bubbleSelect` only take effect in multi-select mode (`multiple` + array value); with both on, the semi-checked state is expressed via `data-contains-selected`/`isIndeterminate`.
- With `toggleBehavior: 'single'`, expansion is accordion-like — only one branch stays expanded (`findParentPath` rebuilds the path).
- `loop` defaults to `true` (keyboard focus wraps around); both `STree` and `STreeVirtualizer` mirror this default in their wrappers, so no extra work is needed when using the headless `TreeRoot` directly.
- Virtualization requires a `height`; the `STreeVirtualizer` `item` slot additionally provides `virtualItem` (for `:data` passthrough and absolute-position styling).
- Expand and collapse animate with a height-collapsing transition on the moved subtree. `STreeVirtualizer` has an opt-in `animated` prop that renders visible items in normal document flow (dynamic mode) so item positions stay correct across expand/collapse without absolute offsets — it is off by default since dynamic measuring is heavier for very large datasets, and while a motion runs the transition list renders fully in document flow before windowing resumes.
- Node text is fully provided by slots — the component has no hardcoded copy, so no localization is needed.

## FAQ

### How do I build a checkable tree?

Use `multiple` with a custom `item` slot that renders a checkbox icon and consumes the `isSelected`/`isIndeterminate` states:

```vue

  <template #item="{ item, isSelected, isIndeterminate }">
    <STreeItem :value="item.value" :level="item.level">
      <SIcon :icon="isIndeterminate ? 'lucide:minus' : isSelected ? 'lucide:check-square' : 'lucide:square'" />
      {{ item.data.label }}
    </STreeItem>
  </template>

```

Add `propagateSelect` to cascade parent selection to descendants, or `bubbleSelect` to auto-select a parent when all its children are selected.

### How do I control the expansion state?

Controlled: `v-model:expanded="expandedKeys"` (array of strings); or uncontrolled with `:default-expanded="['node-1']"`. The expansion event is `update:expanded`.

### How do I optimize for large data?

Use `STreeVirtualizer` with a `height`: only visible nodes render (customize `options.estimateSize` for row height), staying smooth with 1000+ nodes.

```vue

  <template #item="{ item, virtualItem }">
    <STreeVirtualizerItem :value="item.value" :level="item.level" :data="virtualItem">
      {{ item.data.label }}
    </STreeVirtualizerItem>
  </template>

```

### How do I prevent selecting parent nodes?

`allowParentSelect` defaults to `false` — clicking a parent with children only expands/collapses it without selecting. Set `:allow-parent-select="true"` explicitly to allow selecting parents.

### How do I load children asynchronously?

There is no built-in `loadData` contract; load lazily in the `toggle` event and update `items`:

```vue
<STree :items="items" @toggle="event => loadChildren(event.value)">
  

```

Write `children` into the matching node of `items` once loaded (expansion is tracked by `expanded`).

### How do I customize node icons and indentation?

The `item` slot composes freely: compute `padding-left` from `item.level`, switch icons on `item.hasChildren`/`isExpanded`, and style the focus state with `focus:ring-*` classes — see demo 01.

### How does the keyboard work?

`↑/↓` move focus across visible nodes; `→` expands a collapsed node (or enters a child level), `←` collapses (or returns to the parent); `Enter`/`Space` select the current node; typing characters triggers typeahead location; `Shift + ↑/↓` performs range selection in multi-select mode; with `loop` on (default), focus wraps around.

## TreeMenu

- Page URL: /components/tree-menu
- Markdown URL: /components/tree-menu.md
- Description: A collapsible sidebar navigation tree-menu component. STreeMenu combines the headless TreeMenuCompact family of composite components (TreeMenuRoot/TreeMenuOptionCompact/TreeMenuSlotCompact, zero-style) with the TreeMenuRoot context (controlled/uncontrolled activation and expansion, collapsed sidebar mode, flyout submenus when collapsed, action menus); the UI layer only injects the 8-step size recipe and slot classes. The recursive items data model ships with built-in icon/badge/tag/actions/isGroup/link fields, and node content can be freely customized through the item/item-leading/item-trailing slots.

# TreeMenu

## Overview

A collapsible sidebar navigation tree-menu component. `STreeMenu` combines the headless `TreeMenuCompact` family of composite components (`TreeMenuRoot`/`TreeMenuOptionCompact`/`TreeMenuSlotCompact`, zero-style) with the `TreeMenuRoot` context (controlled/uncontrolled activation and expansion, collapsed sidebar mode, flyout submenus when collapsed, action menus); the UI layer only injects the 8-step size recipe and slot classes. The recursive `items` data model ships with built-in `icon`/`badge`/`tag`/`actions`/`isGroup`/link fields, and node content can be freely customized through the `item`/`item-leading`/`item-trailing` slots.

## Usage

Usage examples for tree-menu are rendered on the site.

## Features

- 🧭 Hierarchical data model — `items: TreeMenuOptionData<T>[]` (`value`/`label` plus recursive `children`); the `TreeMenuOptionData<T>` generic preserves custom fields; built-in `isGroup`/`hidden`/`icon`/`badge`/`tag`/`disabled`/`actions`/`to`/`href` fields
- 🎛️ Controlled/uncontrolled dual channels — `modelValue` / `defaultValue` (active item), `expanded` / `defaultExpanded` (expanded items), `collapsed` / `defaultCollapsed` (collapsed state); all support `v-model` and `update:*` events
- 🎯 Expand strategy — `expandStrategy="keep"` (default) preserves manual expansion no matter which menu is selected; `expandStrategy="selected"` auto-expands only the selected menu and its ancestors, collapsing non-selected branches whenever the selected menu changes
- 📉 Collapsed sidebar mode — `collapsed` + `collapsedWidth` (default 50px) / `indent` collapses the rail; items with children render a flyout menu while collapsed, and the expansion state is stashed and restored automatically
- 🧩 Action menus — `actions` + `actionMenuProps` + `onActionSelect` attach hover actions (ellipsis button) to items; the trigger aria-label is localized across 13 language packs
- 🏷️ Badge/tag/icon — built-in `icon`/`badge`/`tag` fields, freely extended via the `item-leading`/`item-trailing` slots
- 🔗 Link items — `to`/`href` render route links or external links (`external` controls behavior); external links show an arrow-up-right icon automatically
- 🗂️ Grouping — `isGroup` groups with the `group-label` slot; `top`/`bottom` slots host menu header/footer content
- 🎨 8 sizes + style injection — `size` from xs to 2xl; `class`/`ui` overrides across 20+ named slots
- ⌨️ Keyboard navigation — WAI-ARIA tree pattern: the root is a single tab stop with `role="tree"`, ↑/↓ roam visible items, → expands or enters children, ← collapses or returns to the parent, Home/End jump to the first/last item, and Enter/Space activates (direction keys only move focus — they never change the active item)
- ♿ Accessibility — `role="tree"`/`treeitem` semantics with `aria-expanded`/`aria-controls`/`aria-selected`, roving tabindex, `data-soybean-tree-menu-*` data attributes, zero axe violations

## Component family

- `STreeMenu` (styled) — entry wrapper; composes `TreeMenuCompact` + the `treeMenuVariants` size recipe + `provideTreeMenuUi` slot-class injection, `useForwardListeners` event merging
- `STreeMenuStyledItem` (styled) — one row drawn with the item recipe, for content that is not a menu node (a brand, a trigger, a footer row); renders through `Primitive`, so `as` / `asChild` pick the element and `disabled` marks the row
- `TreeMenuCompact` (headless) — composite root; `TreeMenuRoot` state root + `TreeMenuOptionsCompact` grouping/recursive rendering + `top`/`bottom` slots
- `TreeMenuRoot` (headless) — state root; `useControllableState` manages activation/expansion/collapse; `backupExpanded` stashes expansion while collapsed and restores it on recovery
- `TreeMenuOptionsCompact` (headless) — grouping/recursive rendering; with `expandStrategy="selected"` it syncs the expanded state to the selected menu path
- `TreeMenuOptionCompact` (headless) — single-node composition; leaves render buttons/links + the action menu, parents render a `TreeMenuCollapsible` trigger + recursive `TreeMenuSub` + a collapsed-mode flyout `DropdownMenuCompact`
- `TreeMenuSlotCompact` (headless) — node content orchestration (icon/label/badge/tag/external-link icon/chevron)
- Base primitives (headless) — `TreeMenuButton`/`TreeMenuItem`/`TreeMenuCollapsible`/`TreeMenuSub`/`TreeMenuGroup`/`TreeMenuGroupLabel`/`TreeMenuTooltipCompact`, all zero-style

## Demos

Interactive demos for tree-menu are rendered on the site.

- 01 Basic — customizer for the sidebar: `expandStrategy` / `collapsed` / `collapsedWidth` / `indent` / `size` controls over groups/icons/badge/tag/action menus/link items

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (17): TreeMenu, TreeMenuBadge, TreeMenuBaseItem, TreeMenuButton, TreeMenuCollapsible, TreeMenuCompact, TreeMenuGroup, TreeMenuGroupLabel, TreeMenuGroupRoot, TreeMenuItem, TreeMenuOptionCompact, TreeMenuOptionsCompact, TreeMenuOptionSlotCompact, TreeMenuRoot, TreeMenuSlotCompact, TreeMenuStyledItem, TreeMenuSub.

### TreeMenu

#### Props
Properties for the TreeMenu component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<Record<TreeMenuUiSlot, ClassValue>>`; optional)
- `modelValue`: the selected value of the tree menu. can be bound-with with `v-model`. (type `string`; optional)
- `defaultValue`: the value of the tree menu when initially rendered. use when you do not need to control the state of the tree. (type `string`; optional)
- `expanded`: the expanded value of the tree menu. can be bound-with with `v-model`. (type `string[]`; optional)
- `defaultExpanded`: the expanded value of the tree menu when initially rendered. use when you do not need to control the state of the tree. (type `string[]`; optional)
- `expandStrategy`: The expand strategy of the tree menu. - `keep`: keep the current expanded state; manually expanded or collapsed menus are not affected by activating other menus. The collapsible ancestors of the selected menu are expanded on mount and whenever the selected menu changes from outside (e.g. driven by an external route), so it stays visible. - `selected`: only expand the currently selected menu and all its ancestor menus; non-selected menus are collapsed when the selected menu changes. (type `TreeMenuExpandStrategy`; default `'keep'`; optional)
- `collapsed`: Whether the tree menu is collapsed. (type `boolean`; default `false`; optional)
- `defaultCollapsed`: The value of the tree menu when it's collapsed. (type `boolean`; optional)
- `collapsedWidth`: The width of the sidebar menu when it's collapsed. (type `number`; default `50`; optional)
- `indent`: The width of the indent. (type `number`; default `16`; optional)
- `pxToRem`: The function to convert pixels to rem. (type `((px: number) => number)`; default `(px: number) => px / 16 (16 is the base font size)`; optional)
- `items`: Items rendered by the component. (type `TreeMenuOptionData<T>[]`; required)
- `groupRootProps`: Properties forwarded to the group root element. (type `TreeMenuGroupRootProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `TreeMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `TreeMenuGroupLabelProps`; optional)
- `showGroupIcon`: Whether to show the group icon. (type `boolean`; default `false`; optional)
- `side`: Horizontal side. (type `HorizontalSide`; optional)
- `itemProps`: Properties forwarded to the item element. (type `TreeMenuItemProps`; optional)
- `buttonProps`: Properties forwarded to the button element. (type `TreeMenuButtonProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `collapsibleProps`: Properties forwarded to the collapsible element. (type `TreeMenuCollapsibleProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `TreeMenuSubProps`; optional)
#### Emits
Events for the TreeMenu component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:expanded`: Emitted when the expanded state changes. (type `[value: string[]]`; parameters `value: string[]`)
- `update:collapsed`: Emitted when the collapsed state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `selectDropdown`: Emitted when select dropdown occurs. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the TreeMenu component.
- `top`: Custom content rendered before the options. (type `(() => any) | undefined`)
- `bottom`: Custom content rendered after the options. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: { item: TreeMenuOptionData<T>; }) => any) | undefined`)
- `item`: Custom content for the item slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: T; }) => any) | undefined`)

### TreeMenuBadge

#### Props
Properties for the badge markup rendered inside a TreeMenu option.

The `badge` family is UI-only (it failed headless admission), so the tree-menu renders its own
badge anatomy instead of composing a headless badge primitive. The shape mirrors the retired
`BadgeCompactProps` minus `content`, which the option supplies through `TreeMenuBaseOptionData.badge`.
- `open`: Whether the badge bubble is rendered. (type `boolean`; default `true`; optional)
- `contentProps`: Properties forwarded to the badge bubble element. (type `BaseProps`; optional)

### TreeMenuBaseItem

#### Props
Properties for the TreeMenuBaseItem component.
- `value`: The unique value of the item. (type `string`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)

### TreeMenuButton

#### Props
Properties for the TreeMenuButton component.
- `disabledSelect`: When `true`, prevents the user from selecting the item. (type `boolean`; default `false`; optional)
- `type`: The type of the button element. Can be one of 'button', 'submit', or 'reset'. (type `ButtonType`; default `'button'`; optional)
- `disabled`: Whether the component is disabled. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TreeMenuCollapsible

#### Props
Properties for the TreeMenuCollapsible component.
- `disabledCollapsible`: When `true`, prevents the user from activating the collapsible trigger. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TreeMenuCompact

#### Props
Properties for the TreeMenuCompact component.
- `modelValue`: the selected value of the tree menu. can be bound-with with `v-model`. (type `string`; optional)
- `defaultValue`: the value of the tree menu when initially rendered. use when you do not need to control the state of the tree. (type `string`; optional)
- `expanded`: the expanded value of the tree menu. can be bound-with with `v-model`. (type `string[]`; optional)
- `defaultExpanded`: the expanded value of the tree menu when initially rendered. use when you do not need to control the state of the tree. (type `string[]`; optional)
- `expandStrategy`: The expand strategy of the tree menu. - `keep`: keep the current expanded state; manually expanded or collapsed menus are not affected by activating other menus. The collapsible ancestors of the selected menu are expanded on mount and whenever the selected menu changes from outside (e.g. driven by an external route), so it stays visible. - `selected`: only expand the currently selected menu and all its ancestor menus; non-selected menus are collapsed when the selected menu changes. (type `TreeMenuExpandStrategy`; default `'keep'`; optional)
- `collapsed`: Whether the tree menu is collapsed. (type `boolean`; default `false`; optional)
- `defaultCollapsed`: The value of the tree menu when it's collapsed. (type `boolean`; optional)
- `collapsedWidth`: The width of the sidebar menu when it's collapsed. (type `number`; default `50`; optional)
- `indent`: The width of the indent. (type `number`; default `16`; optional)
- `pxToRem`: The function to convert pixels to rem. (type `((px: number) => number)`; default `(px: number) => px / 16 (16 is the base font size)`; optional)
- `items`: Items rendered by the component. (type `TreeMenuOptionData<T>[]`; required)
- `groupRootProps`: Properties forwarded to the group root element. (type `TreeMenuGroupRootProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `TreeMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `TreeMenuGroupLabelProps`; optional)
- `showGroupIcon`: Whether to show the group icon. (type `boolean`; default `false`; optional)
- `side`: Horizontal side. (type `HorizontalSide`; optional)
- `itemProps`: Properties forwarded to the item element. (type `TreeMenuItemProps`; optional)
- `buttonProps`: Properties forwarded to the button element. (type `TreeMenuButtonProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `collapsibleProps`: Properties forwarded to the collapsible element. (type `TreeMenuCollapsibleProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `TreeMenuSubProps`; optional)
#### Emits
Events for the TreeMenuCompact component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:expanded`: Emitted when the expanded state changes. (type `[value: string[]]`; parameters `value: string[]`)
- `update:collapsed`: Emitted when the collapsed state changes. (type `[value: boolean]`; parameters `value: boolean`)
- `selectDropdown`: Emitted when select dropdown occurs. (type `[value: string]`; parameters `value: string`)
#### Slots
Slots for the TreeMenuCompact component.
- `top`: Custom content rendered before the options. (type `(() => any) | undefined`)
- `bottom`: Custom content rendered after the options. (type `(() => any) | undefined`)
- `group-label`: Custom content for the group label slot. (type `((props: { item: TreeMenuOptionData<T>; }) => any) | undefined`)
- `item`: Custom content for the item slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: T; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: T; }) => any) | undefined`)

### TreeMenuGroup

#### Props
Properties for the TreeMenuGroup component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TreeMenuGroupLabel

- No documented props, emits, slots, or slot props were available.

### TreeMenuGroupRoot

- No documented props, emits, slots, or slot props were available.

### TreeMenuItem

#### Props
Properties for the TreeMenuItem component.
- `value`: The unique value of the item. (type `string`; required)
- `disabled`: When `true`, prevents the user from interacting with the item. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### TreeMenuOptionCompact

#### Props
Properties for the TreeMenuOptionCompact component.
- `as`: Rendered element tag. (type `AsTag`; optional)
- `item`: Current item data. (type `Omit<TreeMenuBaseOptionData, 'children'> & { children?: TreeMenuOptionData<TreeMenuBaseOptionData>[] | undefined; }`; required)
- `side`: Horizontal side. (type `HorizontalSide`; optional)
- `selectedPaths`: The selected paths of the tree menu, used to determine whether the current item is selected or has selected descendants. (type `string[]`; optional)
- `itemProps`: Properties forwarded to the item element. (type `TreeMenuItemProps`; optional)
- `buttonProps`: Properties forwarded to the button element. (type `TreeMenuButtonProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `collapsibleProps`: Properties forwarded to the collapsible element. (type `TreeMenuCollapsibleProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `TreeMenuSubProps`; optional)
#### Emits
Events for the TreeMenuOptionCompact component.
- `selectDropdown`: Emitted when select dropdown occurs. (type `[value: string]`; parameters `value: string`)

### TreeMenuOptionsCompact

#### Props
Properties for the TreeMenuOptionsCompact component.
- `items`: Items rendered by the component. (type `TreeMenuOptionData<T>[]`; required)
- `groupRootProps`: Properties forwarded to the group root element. (type `TreeMenuGroupRootProps`; optional)
- `groupProps`: Properties forwarded to the group element. (type `TreeMenuGroupProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element. (type `TreeMenuGroupLabelProps`; optional)
- `showGroupIcon`: Whether to show the group icon. (type `boolean`; default `false`; optional)
- `side`: Horizontal side. (type `HorizontalSide`; optional)
- `itemProps`: Properties forwarded to the item element. (type `TreeMenuItemProps`; optional)
- `buttonProps`: Properties forwarded to the button element. (type `TreeMenuButtonProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `collapsibleProps`: Properties forwarded to the collapsible element. (type `TreeMenuCollapsibleProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `TreeMenuSubProps`; optional)
#### Emits
Events for the TreeMenuOptionsCompact component.
- `selectDropdown`: Emitted when select dropdown occurs. (type `[value: string]`; parameters `value: string`)

### TreeMenuOptionSlotCompact

#### Props
Slot properties for the TreeMenuOptionCompact component.
- `showLinkIcon`: Whether to show the link icon. (type `boolean`; optional)
- `as`: Rendered element tag. (type `AsTag`; optional)
- `item`: Current item data. (type `Omit<TreeMenuBaseOptionData, 'children'> & { children?: TreeMenuOptionData<TreeMenuBaseOptionData>[] | undefined; }`; required)
- `side`: Horizontal side. (type `HorizontalSide`; optional)
- `selectedPaths`: The selected paths of the tree menu, used to determine whether the current item is selected or has selected descendants. (type `string[]`; optional)
- `itemProps`: Properties forwarded to the item element. (type `TreeMenuItemProps`; optional)
- `buttonProps`: Properties forwarded to the button element. (type `TreeMenuButtonProps`; optional)
- `linkProps`: Properties forwarded to the link element. (type `LinkExtraProps`; optional)
- `collapsibleProps`: Properties forwarded to the collapsible element. (type `TreeMenuCollapsibleProps`; optional)
- `subProps`: Properties forwarded to the sub element. (type `TreeMenuSubProps`; optional)

### TreeMenuRoot

#### Props
Properties for the TreeMenuRoot component.
- `modelValue`: the selected value of the tree menu. can be bound-with with `v-model`. (type `string`; optional)
- `defaultValue`: the value of the tree menu when initially rendered. use when you do not need to control the state of the tree. (type `string`; optional)
- `expanded`: the expanded value of the tree menu. can be bound-with with `v-model`. (type `string[]`; optional)
- `defaultExpanded`: the expanded value of the tree menu when initially rendered. use when you do not need to control the state of the tree. (type `string[]`; optional)
- `expandStrategy`: The expand strategy of the tree menu. - `keep`: keep the current expanded state; manually expanded or collapsed menus are not affected by activating other menus. The collapsible ancestors of the selected menu are expanded on mount and whenever the selected menu changes from outside (e.g. driven by an external route), so it stays visible. - `selected`: only expand the currently selected menu and all its ancestor menus; non-selected menus are collapsed when the selected menu changes. (type `TreeMenuExpandStrategy`; default `'keep'`; optional)
- `collapsed`: Whether the tree menu is collapsed. (type `boolean`; default `false`; optional)
- `defaultCollapsed`: The value of the tree menu when it's collapsed. (type `boolean`; optional)
- `collapsedWidth`: The width of the sidebar menu when it's collapsed. (type `number`; default `50`; optional)
- `indent`: The width of the indent. (type `number`; default `16`; optional)
- `pxToRem`: The function to convert pixels to rem. (type `((px: number) => number)`; default `(px: number) => px / 16 (16 is the base font size)`; optional)
#### Emits
Events for the TreeMenuRoot component.
- `update:modelValue`: Emitted when the model value changes. (type `[value: string]`; parameters `value: string`)
- `update:expanded`: Emitted when the expanded state changes. (type `[value: string[]]`; parameters `value: string[]`)
- `update:collapsed`: Emitted when the collapsed state changes. (type `[value: boolean]`; parameters `value: boolean`)

### TreeMenuSlotCompact

- No documented props, emits, slots, or slot props were available.

### TreeMenuStyledItem

#### Props
Properties for the TreeMenuStyledItem component.
- `class`: Additional class names applied to the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<Record<TreeMenuStyledItemUiSlot, ClassValue>>`; optional)
- `disabled`: Whether the row is disabled. The row carries `data-disabled` — what the recipe's disabled styles key on — and `aria-disabled`. A native `button` row additionally gets the `disabled` attribute; every other element only declares the state, so nested content (for example a trigger inside the row) decides how it blocks itself. (type `boolean`; default `false`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Slots
Slots for the TreeMenuStyledItem component.
- `default`: Content of the row. (type `(() => any) | undefined`)

### TreeMenuSub

#### Props
Properties for the TreeMenuSub component.
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`TreeMenuRoot` owns all state (activation/expansion/collapse through the `useControllableState` controlled/uncontrolled dual channels). On collapse it stashes the expanded branches via `backupExpanded`, clears expansion, and triggers the flyout menus; on recovery it restores the branches verbatim — a lossless collapse/expand round trip. Composition happens in the headless layer: `TreeMenuOptionCompact` orchestrates leaves (button/link + action menu) and parents (Collapsible trigger + recursive `TreeMenuSub` + flyout menu), while the UI `STreeMenu` only injects the size recipe and slot classes and carries no state. Both the action menu and the flyout menu reuse the data-driven `DropdownMenuCompact` (rendered by `MenuOptions`). The root follows the WAI-ARIA tree pattern — a single roving tab stop with `role="tree"`, `treeitem` items, and `group` sub-lists — and the axe scan reports zero violations. Compared with mainstream sidebar-menu libraries, SoybeanUI is more complete in headless separation, built-in action menus, collapsed flyouts, external link items, and 13-language localization.

| Capability                            | SoybeanUI | Ant Design | Element Plus | Naive UI |
| :------------------------------------ | :-------: | :--------: | :----------: | :------: |
| headless/style separation             |    ✅     |     —      |      —       |    —     |
| Controlled activation/expand/collapse |    ✅     |     ✅     |      ✅      |    ✅    |
| Collapsed sidebar (rail width)        |    ✅     |     ✅     |      ✅      |    ⚠️    |
| Flyout submenus when collapsed        |    ✅     |     ✅     |      ✅      |    ⚠️    |
| Built-in action menus (actions)       |    ✅     |     —      |      —       |    —     |
| Badge/tag (badge/tag)                 |    ✅     |     ⚠️     |      —       |    —     |
| Groups/icons/external links           |    ✅     |     ✅     |      ✅      |    ✅    |
| Localized aria-label                  |    ✅     |     ✅     |      ✅      |    ✅    |

`⚠️` = partial support (Naive UI needs extra `collapsed` + custom popup content for flyouts; Ant Design implements badges through custom `label` nodes).

### Cautions

- Keyboard navigation follows the WAI-ARIA tree pattern: ↑/↓ (and Home/End) roam the visible items without wrapping, → expands a closed branch then enters its first child, ← collapses an expanded branch then returns to the parent, and Enter/Space activate the focused item. Direction keys only move focus — the active item only changes on explicit activation.
- In collapsed mode the flyout branch popups are owned by the Menu machinery; the tree roaming applies to the rail items only.
- In collapsed mode (`collapsed`) the action menu (`actions`) is hidden; the action button only renders in expanded mode.
- The collapsed flyout defaults to `hover` triggering; switch it via `dropdownMenuProps.trigger: 'click'`.
- Toggling `collapsed` stashes and restores the expansion state; the original expanded branches survive the collapse round trip.
- The action button's accessible name comes from the `treeMenu.openActions` template (with the `{label}` placeholder) and follows the `ConfigProvider` locale across 13 languages.
- A node's `disabled` blocks activation/expansion/actions; disabled items render `data-disabled` and native `disabled` semantics.
- Clicking a leaf activates it and emits `update:modelValue`; clicking an item with children toggles expansion and emits `update:expanded`.
- With `expandStrategy="selected"` the expanded state is re-synced to the selected menu path whenever the selected menu changes or the strategy switches to `selected`; manually expanded non-selected branches stay open until the next selection.
- Data attributes use only `data-soybean-tree-menu-*` (D1-07) with no redundant attributes.
- `size` supports 8 steps from xs to 2xl; style overrides are injected via `ui` (20+ named slots) and the root `class`.

## FAQ

### Which keyboard shortcuts does the tree menu support?

The menu is a single tab stop following the WAI-ARIA tree pattern: entering the tree focuses the active item (or the first one), ↑/↓ roam visible items (skipping disabled ones), → expands a closed branch and a second press enters its first child, ← collapses or returns to the parent, Home/End jump to the first/last visible item, and Enter/Space activate.

### How do I build a collapsible sidebar menu?

Bind `v-model:collapsed` to the collapsed state; `collapsedWidth` (default 50px) controls the rail width and `indent` the child indentation:

```vue

```

### How do flyout submenus work when collapsed?

Items with children automatically render a flyout menu in collapsed mode (default `hover` trigger; switch to `click` via `dropdownMenuProps.trigger`). The flyout's active state is synced with `modelValue`.

### How do I add action buttons to an item?

```vue

{ label: 'Design Engineering', value: 'design-engineering', actions: [ { label: 'Edit', value: 'edit', icon:
'lucide:pencil' }, { label: 'Delete', value: 'delete', icon: 'lucide:trash' } ], onActionSelect: action =>
console.log('select', action.value) }
```

Hovering the item reveals an ellipsis button at the end; clicking it opens the action menu. The button aria-label is localized automatically (`Open {label} actions`).

### How do I control the active and expanded items?

Controlled: `v-model:modelValue="active"`, `v-model:expanded="expandedKeys"`, `v-model:collapsed="collapsed"`; uncontrolled initial values use `default-value` / `default-expanded` / `default-collapsed`. The activation event is `update:modelValue` and the expansion event is `update:expanded`.

### What is the difference between the `keep` and `active` expand strategies?

`expandStrategy` decides how the expanded state relates to the active menu. With `keep` (default) expansion is purely manual: activating another menu never changes what is expanded or collapsed. With `active` the menu follows the active item — whenever the active menu changes (or you switch to `active`), only the active menu and all its ancestor menus stay expanded and every other branch collapses:

```vue

```

Use `keep` for free-form browsing where the user controls every branch, and `active` for navigation-driven sidebars where the current route's path should always stay visible.

### How do I create groups?

Set `isGroup: true` on a node with `children` to turn it into a group; customize the group title through the `group-label` slot:

```vue

  <template #group-label="{ item }">{{ item.label }} ({{ item.children.length }})</template>

```

### How do I add link items?

```vue
{ label: 'Soybean UI', value: 'soybean-ui', href: 'https://ui.soybeanjs.cn' } { label: 'About', value: 'about', to:
'/about' }
```

External links automatically show the arrow-up-right icon; `external: true` forces external-link handling.

### How do I customize icons, badges, and tags?

Built-in fields: `icon` (icon), `badge` + `badgeProps` (badge), `tag` + `tagProps` (tag). For richer content use the `item-leading`/`item-trailing`/`item` slots:

```vue

  <template #item-leading="{ item }">
    <span class="text-primary">{{ item.label.slice(0, 1) }}</span>
  </template>

```

### How do I disable an item?

Set `disabled: true` on the node to block activation/expansion/actions; disabled items render `data-disabled` and native `disabled` semantics.

### How do I style a custom row like a menu item?

Render `STreeMenuStyledItem` — it is the row the menu items themselves are drawn with, so it takes the same size recipe, the same icon column, and the same fold: inside a collapsed ancestor (`group` + `data-state="collapsed"`) the row narrows to the item's icon width. Pass `size` to match the menu, `as` / `asChild` when the row is not a button (a `div` for a non-interactive brand, `asChild` to merge into your own link), and `disabled` to mark it. When the row folds it is icon-only, so hide the label yourself and center the icon — a mark wider than the folded content box would otherwise sit against the row's trailing edge: `:ui="{ button: 'group-data-[state=collapsed]:justify-center' }"`.

### How is the action button aria-label localized?

Switch the `ConfigProvider` locale (13 built-in language packs); the action button uses the `treeMenu.openActions` template — `Open {label} actions` — where `{label}` is replaced by the item label.

## TreeNav

- Page URL: /components/tree-nav
- Markdown URL: /components/tree-nav.md
- Description: TreeNav is a data-driven horizontal navigation bar with a persistent selection state: top-level entries sit in a row, branch entries open dropdown popups (hover by default), and selecting any leaf keeps the whole ancestor chain highlighted.

# TreeNav

## Overview

TreeNav is a data-driven horizontal navigation bar with a persistent selection state: top-level entries sit in a row, branch entries open dropdown popups (hover by default), and selecting any leaf keeps the whole ancestor chain highlighted.

`STreeNav` is the horizontal counterpart of `STreeMenu`: both consume the same tree-shaped `items` data (`TreeNavOptionData`) and derive highlights from the selected value, but TreeNav renders branches as DropdownMenu popups instead of collapsible sections. Logic and accessibility semantics live in the headless `TreeNavCompact`; styles are injected through an `scv()` recipe.

> Unlike Menubar (a transient "which menu is open" command-menu model), TreeNav models **selection**: opening a popup never marks anything active — only selection does. Selected leaves carry `data-selected`, and ancestors of the selected leaf carry `data-child-selected`.

## Features

- **Persistent selection** — bind `modelValue` (`v-model`) or seed with `defaultValue`; selection survives closing popups and page interactions.
- **Highlight derivation** — the selected leaf renders `data-selected="true"`, and every ancestor in its path renders `data-child-selected`; derivation reuses the shared tree-path helper, so highlighting works at any depth.
- **Hover-first popups** — branch popups open on hover by default (`trigger="click"` to override), tuned via `delayDuration` / `skipDelayDuration`.
- **Familiar data shape** — pass one `items` array (`TreeNavOptionData`: `value` / `label` / `icon` / `children` / `href` / `to` / `disabled` …), aligned with TreeMenu's option model; item customization beyond these fields (badges, tags, actions…) is provided via slots instead of extra data fields.
- **Link top-level items** — items with `href` / `to` render as links that also update the selection on click.
- **Overflow collapsing** — with `collapsible`, trailing top-level items merge into a trailing "more" popup so the bar always fits its container; customize via `moreLabel` / `moreIcon` / `moreProps` / the `more-trigger` slot.
- **Navigation semantics** — root renders as `<nav>` (`as` overridable); popup trigger semantics (`aria-haspopup` / `aria-expanded`, Escape handling) are inherited from the DropdownMenu layer.
- **Keyboard navigation** — the top level is a single roving tab stop: ←/→ roam all entries alike (skipping disabled, no wrap), Home/End jump to the first/last entry; branch popups open through the explicit keys — Enter/Space (native button semantics) or ArrowDown — and once a popup is open its keys are owned by the Menu machinery.
- **Per-item and whole-bar disabling** — `item.disabled` makes a single entry inert; the bar-level `disabled` disables everything.
- **Hidden items** — `item.hidden` drops the entry and its subtree from the bar and its popup; a branch whose children are all hidden renders as a plain leaf.
- **Six sizes & two variants** — `size` (xs…2xl) plus `variant="default"` (subtle card surface) or `variant="nav"` (bare bar).
- **Slot passthrough** — `item` / `item-leading` / `item-trailing` / `item-trigger-icon` / `item-link-icon` forward into both the top level and popups.
- **Headless composition** — import from `@soybeanjs/headless/tree-nav` for unstyled data-driven usage; popup options reuse `MenuOptionsCompact`.

## Usage

Usage examples for tree-nav are rendered on the site.

## Demos

Interactive demos for tree-nav are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (6): TreeNav, TreeNavCompact, TreeNavOptionCompact, TreeNavOptionsCompact, TreeNavOverflow, TreeNavRoot.

### TreeNav

#### Props
Properties for the TreeNav component.
- `class`: class of tree-nav root. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `size`: Visual size of the component. (type `ThemeSize`; optional)
- `ui`: Per-slot class overrides for the component. (type `Partial<TreeNavUi>`; optional)
- `collapsible`: Whether top-level overflow items collapse into a trailing "more" branch popup so the bar always fits inside its container. (type `boolean`; default `false`; optional)
- `modelValue`: The value of the currently selected item. Can be used as `v-model`. (type `string`; optional)
- `defaultValue`: The value of the item that should be selected when initially rendered. (type `string`; optional)
- `dir`: The reading direction of the component when applicable. (type `Direction`; optional)
- `trigger`: How branch popups are opened. - `click`: The popup will be opened when the trigger is clicked. - `hover`: The popup will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'hover'`; optional)
- `delayDuration`: The duration from when the pointer enters a branch trigger until the popup gets opened in hover mode. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another branch trigger without incurring a delay again. (type `number`; default `300`; optional)
- `placement`: The preferred placement of branch popups relative to their trigger. (type `Placement`; default `'bottom-start'`; optional)
- `showArrow`: Whether branch popups show an arrow. (type `boolean`; default `false`; optional)
- `disabled`: Whether the whole navigation bar is disabled. (type `boolean`; optional)
- `linkProps`: Properties forwarded to the link element of link items. (type `LinkExtraProps`; optional)
- `itemProps`: Properties forwarded to the item element of popup items. (type `MenuItemProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element of popup group labels. (type `MenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element of popup items. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element of popup separators. (type `MenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element of popup branches. (type `MenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element of popup branches. (type `MenuSubContentProps`; optional)
- `portalProps`: Properties forwarded to the portal element of popups. (type `MenuPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element of popups. (type `MenuPopupProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element of branch popups. (type `DropdownMenuTriggerProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element of popups. (type `MenuArrowProps`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `items`: Top-level items rendered as visible entries. (type `TreeNavOptionData<TreeNavBaseOptionData>[]`; required)
- `moreItems`: Items collapsed into the trailing "more" popup. (type `TreeNavOptionData<TreeNavBaseOptionData>[]`; optional)
- `moreLabel`: Label of the trailing "more" trigger. (type `string`; default `'More'`; optional)
- `moreIcon`: Icon of the trailing "more" trigger. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; default `'lucide:ellipsis'`; optional)
- `moreProps`: Properties forwarded to the trailing "more" trigger button. (type `ButtonProps`; optional)
#### Emits
Events for the TreeNav component.
- `update:modelValue`: Emitted when the selected value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when an item is selected. (type `[item: TreeNavOptionData<TreeNavBaseOptionData>, event: Event]`; parameters `item: TreeNavOptionData<TreeNavBaseOptionData>, event: Event`)
#### Slots
Slots for the TreeNav component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<DefinedValue>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `more-trigger`: Custom content for the trailing "more" trigger when present. (type `((props: TreeNavMoreEntry) => any) | undefined`)

### TreeNavCompact

#### Props
Properties for the TreeNavCompact component.
- `collapsible`: Whether top-level overflow items collapse into a trailing "more" branch popup so the bar always fits inside its container. (type `boolean`; default `false`; optional)
- `modelValue`: The value of the currently selected item. Can be used as `v-model`. (type `string`; optional)
- `defaultValue`: The value of the item that should be selected when initially rendered. (type `string`; optional)
- `dir`: The reading direction of the component when applicable. (type `Direction`; optional)
- `trigger`: How branch popups are opened. - `click`: The popup will be opened when the trigger is clicked. - `hover`: The popup will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'hover'`; optional)
- `delayDuration`: The duration from when the pointer enters a branch trigger until the popup gets opened in hover mode. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another branch trigger without incurring a delay again. (type `number`; default `300`; optional)
- `placement`: The preferred placement of branch popups relative to their trigger. (type `Placement`; default `'bottom-start'`; optional)
- `showArrow`: Whether branch popups show an arrow. (type `boolean`; default `false`; optional)
- `disabled`: Whether the whole navigation bar is disabled. (type `boolean`; optional)
- `linkProps`: Properties forwarded to the link element of link items. (type `LinkExtraProps`; optional)
- `itemProps`: Properties forwarded to the item element of popup items. (type `MenuItemProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element of popup group labels. (type `MenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element of popup items. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element of popup separators. (type `MenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element of popup branches. (type `MenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element of popup branches. (type `MenuSubContentProps`; optional)
- `portalProps`: Properties forwarded to the portal element of popups. (type `MenuPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element of popups. (type `MenuPopupProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element of branch popups. (type `DropdownMenuTriggerProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element of popups. (type `MenuArrowProps`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
- `items`: Top-level items rendered as visible entries. (type `TreeNavOptionData<TreeNavBaseOptionData>[]`; required)
- `moreItems`: Items collapsed into the trailing "more" popup. (type `TreeNavOptionData<TreeNavBaseOptionData>[]`; optional)
- `moreLabel`: Label of the trailing "more" trigger. (type `string`; default `'More'`; optional)
- `moreIcon`: Icon of the trailing "more" trigger. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; default `'lucide:ellipsis'`; optional)
- `moreProps`: Properties forwarded to the trailing "more" trigger button. (type `ButtonProps`; optional)
#### Emits
Events for the TreeNavCompact component.
- `update:modelValue`: Emitted when the selected value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when an item is selected. (type `[item: TreeNavOptionData<TreeNavBaseOptionData>, event: Event]`; parameters `item: TreeNavOptionData<TreeNavBaseOptionData>, event: Event`)
#### Slots
Slots for the TreeNavCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<DefinedValue>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `more-trigger`: Custom content for the trailing "more" trigger when present. (type `((props: TreeNavMoreEntry) => any) | undefined`)

### TreeNavOptionCompact

#### Props
Properties for the TreeNavOptionCompact component.
- `item`: Current item data. (type `Omit<TreeNavBaseOptionData, 'children'> & { children?: TreeNavOptionData<TreeNavBaseOptionData>[] | undefined; }`; required)
- `childSelected`: Whether the selected leaf lives inside this branch subtree. (type `boolean`; optional)

### TreeNavOptionsCompact

#### Props
Properties for the TreeNavOptionsCompact component.
- `items`: Top-level items rendered as visible entries. (type `TreeNavOptionData<TreeNavBaseOptionData>[]`; required)
- `moreItems`: Items collapsed into the trailing "more" popup. (type `TreeNavOptionData<TreeNavBaseOptionData>[]`; optional)
- `moreLabel`: Label of the trailing "more" trigger. (type `string`; default `'More'`; optional)
- `moreIcon`: Icon of the trailing "more" trigger. (type `string | import("vue").Component | import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, { [...`; default `'lucide:ellipsis'`; optional)
- `moreProps`: Properties forwarded to the trailing "more" trigger button. (type `ButtonProps`; optional)
#### Slots
Slots for the TreeNavOptionsCompact component.
- `item`: Custom content for the item slot. (type `((props: { item: MenuOptionData<DefinedValue>; isTrigger?: boolean; }) => any) | undefined`)
- `item-leading`: Custom content for the item leading slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-trailing`: Custom content for the item trailing slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-trigger-icon`: Custom content for the item trigger icon slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `item-link-icon`: Custom content for the item link icon slot. (type `((props: { item: MenuOptionData<DefinedValue>; }) => any) | undefined`)
- `more-trigger`: Custom content for the trailing "more" trigger when present. (type `((props: TreeNavMoreEntry) => any) | undefined`)

### TreeNavOverflow

- No documented props, emits, slots, or slot props were available.

### TreeNavRoot

#### Props
Properties for the TreeNavRoot component.
- `modelValue`: The value of the currently selected item. Can be used as `v-model`. (type `string`; optional)
- `defaultValue`: The value of the item that should be selected when initially rendered. (type `string`; optional)
- `dir`: The reading direction of the component when applicable. (type `Direction`; optional)
- `trigger`: How branch popups are opened. - `click`: The popup will be opened when the trigger is clicked. - `hover`: The popup will be opened when the trigger is hovered. (type `DropdownMenuTriggerType`; default `'hover'`; optional)
- `delayDuration`: The duration from when the pointer enters a branch trigger until the popup gets opened in hover mode. (type `number`; default `150`; optional)
- `skipDelayDuration`: How much time a user has to enter another branch trigger without incurring a delay again. (type `number`; default `300`; optional)
- `placement`: The preferred placement of branch popups relative to their trigger. (type `Placement`; default `'bottom-start'`; optional)
- `showArrow`: Whether branch popups show an arrow. (type `boolean`; default `false`; optional)
- `disabled`: Whether the whole navigation bar is disabled. (type `boolean`; optional)
- `linkProps`: Properties forwarded to the link element of link items. (type `LinkExtraProps`; optional)
- `itemProps`: Properties forwarded to the item element of popup items. (type `MenuItemProps`; optional)
- `groupLabelProps`: Properties forwarded to the group label element of popup group labels. (type `MenuGroupLabelProps`; optional)
- `shortcutProps`: Properties forwarded to the shortcut element of popup items. (type `MenuShortcutProps`; optional)
- `separatorProps`: Properties forwarded to the separator element of popup separators. (type `MenuSeparatorProps`; optional)
- `subTriggerProps`: Properties forwarded to the sub trigger element of popup branches. (type `MenuSubTriggerProps`; optional)
- `subContentProps`: Properties forwarded to the sub content element of popup branches. (type `MenuSubContentProps`; optional)
- `portalProps`: Properties forwarded to the portal element of popups. (type `MenuPortalProps`; optional)
- `popupProps`: Properties forwarded to the popup element of popups. (type `MenuPopupProps`; optional)
- `triggerProps`: Properties forwarded to the trigger element of branch popups. (type `DropdownMenuTriggerProps`; optional)
- `arrowProps`: Properties forwarded to the arrow element of popups. (type `MenuArrowProps`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)
#### Emits
Events for the TreeNavRoot component.
- `update:modelValue`: Emitted when the selected value changes. (type `[value: string]`; parameters `value: string`)
- `select`: Emitted when an item is selected. (type `[item: TreeNavOptionData<TreeNavBaseOptionData>, event: Event]`; parameters `item: TreeNavOptionData<TreeNavBaseOptionData>, event: Event`)
#### Slots
Slots for the TreeNavRoot component.
- `default`: Default content rendered inside the nav root. (type `(() => any) | undefined`)

## Notes

### When to use which navigation component

| Component   | State model                                   | Layout     | Use for                               |
| :---------- | :-------------------------------------------- | :--------- | :------------------------------------ |
| `SMenubar`  | open menu (`modelValue` = which menu is open) | horizontal | application command menus (File/Edit) |
| `SNavMenu`  | highlighted item (`modelValue`)               | horizontal | site-level nav with flyout panels     |
| `STreeMenu` | persistent selection                          | vertical   | sidebar navigation                    |
| `STreeNav`  | persistent selection                          | horizontal | top navigation bars                   |

### Runtime considerations

1. **Open ≠ active** — popup open state is transient UI state managed internally by the DropdownMenu layer; only leaf selection updates `data-selected`. Do not use `SMenubar`'s `modelValue` semantics here.
2. **Collapsed highlight consistency** — when a selected item collapses into the "more" popup, its visible ancestor still shows `data-child-selected` because derivation runs on the full `items` list.
3. **Collapsible measurement** — like Menubar's overflow collapsing, measurement runs against real layout after mount; give the parent a constrained width (e.g. `max-w-*` / fixed width) for best results. The first frame may briefly render all items before collapsing.
4. **Controlled mode** — with `modelValue`, internal writes only emit `update:modelValue`; uncontrolled usage seeds the initial state with `defaultValue`.
5. **Keyboard model** — while the bar is closed, ←/→ (and Home/End) roam the top level through a roving tabindex; branch triggers are roam targets like any other entry, so arrows never open popups. Opening stays on Enter/Space or ArrowDown (focus then moves to the first menu item); once a popup is open, all keys belong to the Menu (↑/↓ inside, Escape to close and return focus to the trigger), and a hover popup closes itself when focus leaves the trigger.

## FAQ

### Which keyboard shortcuts does the nav bar support?

←/→ roam the top-level entries (Home/End jump to the ends) — branch triggers included, so the arrows only move focus and never open popups. Popups open via Enter/Space or ArrowDown on a branch trigger (focus lands on the first menu item). Direction keys never change the selection — selection only happens on explicit activation (click or Enter/Space on a leaf).

### How do I make a top-level entry navigate instead of opening a dropdown?

Set `href` or `to` on the item — link entries render as `<a>` elements and update the selection on click.

### How do I control which entry stays highlighted?

Bind `v-model`. The selected value is compared against the whole `items` tree; matched leaves get `data-selected` and their ancestors get `data-child-selected`.

### Why doesn't hovering a branch mark it active?

Opening a popup is transient state, not selection — select a leaf inside instead. This mirrors `STreeMenu`, where container nodes never carry the active state.

### What happens when my nav bar overflows?

Pass `collapsible`. Trailing items collapse into a "more" popup (default label `More`) whenever they exceed the container width, recomputed automatically on resize.

## Virtualizer

- Page URL: /components/virtualizer
- Markdown URL: /components/virtualizer.md
- Description: A virtual scrolling component that efficiently renders large lists by only rendering items currently in the viewport. SVirtualizer wraps the headless VirtualizerRoot/VirtualizerContent primitives (built on @tanstack/vue-virtual) — only the visible window of items is mounted into the DOM, keeping large lists fast.

# Virtualizer

## Overview

A virtual scrolling component that efficiently renders large lists by only rendering items currently in the viewport. `SVirtualizer` wraps the headless `VirtualizerRoot`/`VirtualizerContent` primitives (built on `@tanstack/vue-virtual`) — only the visible window of items is mounted into the DOM, keeping large lists fast.

Use a virtualizer for long lists/tables where rendering all rows would be slow. For a listbox/tree with virtual scrolling, see the higher-level integrations (e.g. `select`, `tree`).

## Usage

Usage examples for virtualizer are rendered on the site.

## Features

- ⚡ Virtual scrolling — built on `@tanstack/vue-virtual`; only viewport-visible items render
- 📊 Data-driven — pass `items` (any record shape) and `estimateSize` for row height
- 📏 Scroll container — `height` sets the root scroll viewport (with `overflow: auto`)
- ↔️ Orientation — `options.horizontal` renders a horizontally scrolling row
- 🎚️ TanStack options — pass `options` (`overscan`, `scrollMargin`, `paddingStart/End`, measurement overrides, …)
- 🔁 Dynamic mode — `dynamic` enables variable-height item measurement
- 🧩 Item slot — the `item` slot receives `{ virtualItem, index, item }` for custom rendering
- ♿ Accessible — root is keyboard-scrollable (`tabindex="-1"`) and exposes virtualized content

## Component family

- `SVirtualizer` (styled) — the entry wrapper; iterates `virtualItems` into the `item` slot
- `VirtualizerRoot` (headless) — the scroll container; owns the `useVirtualizer` instance, computes `virtualItems`/`totalSize`/`contentStyle`
- `VirtualizerContent` (headless) — the sized inner content that positions virtual items
- `VirtualizerItem` (headless) — a positioned virtual item (used by advanced custom builds)

## Demos

Interactive demos for virtualizer are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (5): Virtualizer, VirtualizerContent, VirtualizerDynamicContent, VirtualizerItem, VirtualizerRoot.

### Virtualizer

#### Props
Properties for the Virtualizer component.
- `contentProps`: Properties forwarded to the content element. (type `VirtualizerContentProps`; optional)
- `dynamicContentProps`: Properties forwarded to the dynamic content element. (type `VirtualizerDynamicContentProps`; optional)
- `height`: The height of the virtualizer root (type `string | number`; required)
- `items`: Items rendered by the component. (type `T[]`; required)
- `options`: Options. (type `VirtualizerOptions`; optional)
- `dynamic`: Whether dynamic. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### VirtualizerContent

#### Props
Properties for the VirtualizerContent component.
- `dynamicContentProps`: Properties forwarded to the dynamic content element. (type `VirtualizerDynamicContentProps`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### VirtualizerDynamicContent

- No documented props, emits, slots, or slot props were available.

### VirtualizerItem

#### Props
Properties for the VirtualizerItem component.
- `data`: Data. (type `VirtualItem`; required)
- `customStyle`: Whether custom style. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

### VirtualizerRoot

#### Props
Properties for the VirtualizerRoot component.
- `height`: The height of the virtualizer root (type `string | number`; required)
- `items`: Items rendered by the component. (type `T[]`; required)
- `options`: Options. (type `VirtualizerOptions`; optional)
- `dynamic`: Whether dynamic. (type `boolean`; optional)
- `asChild`: Change the default rendered element for the one passed as a child, merging their props and behavior. (type `boolean`; optional)
- `as`: The element or component this component should render as. Can be overwrite by `asChild` (type `AsTag | Component`; default `'div'`; optional)

## Notes

### Architecture and benchmark differences

`VirtualizerRoot` owns the `@tanstack/vue-virtual` instance and computes `virtualItems`/`totalSize`/`contentStyle`, while `SVirtualizer` only iterates the virtual items into the `item` slot. This delegates the measurement/positioning engine to the industry-standard TanStack Virtual (the same engine used by shadcn-ui/TanStack). Ant Design (`rc-virtual-list`), Element Plus (`el-table-v2`), Mantine (`ListVirtualization`) and Naive UI (`virtual-list`) provide their own virtual engines; SoybeanUI exposes a thin, engine-agnostic wrapper so any `@tanstack/vue-virtual` option can flow through.

| Capability          | SoybeanUI | TanStack | Ant Design | Element Plus | Mantine | Naive UI |
| :------------------ | :-------: | :------: | :--------: | :----------: | :-----: | :------: |
| Virtual engine      |    ✅     |    ✅    |     ✅     |      ✅      |   ✅    |    ✅    |
| Data-driven items   |    ✅     |    ✅    |     ✅     |      ✅      |   ✅    |    ✅    |
| Horizontal mode     |    ✅     |    ✅    |     ✅     |      ✅      |    —    |    —     |
| Dynamic measurement |    ✅     |    ✅    |     —      |      —       |    —    |    —     |
| Full engine options |    ✅     |    ✅    |     —      |      —       |    —    |    —     |

`—` = unsupported or a different interaction model.

### Cautions

- `height` sets the root scroll viewport; `estimateSize` provides the row size used before measurement.
- `items` can be any record shape; the `item` slot receives `{ virtualItem, index, item }`.
- Pass `options` (from `@tanstack/vue-virtual`) for `overscan`, `horizontal`, `scrollMargin`, measurement overrides, etc.
- `dynamic` enables variable-height item measurement; otherwise rows are measured once and reused.
- This is a low-level primitive — for listbox/tree virtual scrolling use the higher-level components that wrap it.

### Roadmap

N/A — virtualizer is feature-complete for the current parity set.

## FAQ

### How do I render a large list?

Pass `items`, a row `estimate-size` and a `height`, with an `item` slot:

```vue

  <template #item="{ item }">{{ item.label }}</template>

```

### How do I scroll horizontally?

Set `options.horizontal`:

```vue

```

### How do I tune overscan?

Pass `overscan` in `options`:

```vue

```

### How do I support variable-height items?

Set `dynamic`:

```vue

  <template #item="{ item, virtualItem }">{{ item.label }}</template>

```

## Visually Hidden

- Page URL: /components/visually-hidden
- Markdown URL: /components/visually-hidden.md
- Description: VisuallyHidden is a utility component that hides content from the screen but keeps it accessible to screen readers. It is essential for accessibility when you want to provide context to users relying on assistive technologies without affecting the visual design.

# Visually Hidden

## Overview

`VisuallyHidden` is a utility component that hides content from the screen but keeps it accessible to screen readers. It is essential for accessibility when you want to provide context to users relying on assistive technologies without affecting the visual design.

> Note: This component is exported from `@soybeanjs/headless`.

## Usage

Usage examples for visually-hidden are rendered on the site.

## API

### Props

### Slots

## Watermark

- Page URL: /components/watermark
- Markdown URL: /components/watermark.md
- Description: SWatermark overlays a repeating text or image pattern on top of page content to indicate ownership, confidentiality, or branding. It generates a tiled canvas data URL as the overlay's background-image, supports text and image watermarks with rotation, gap, offset, and cross-pattern configuration, and includes an optional anti-tamper defense mechanism that automatically restores the overlay if it is removed or modified via DevTools.

# Watermark

## Overview

`SWatermark` overlays a repeating text or image pattern on top of page content to indicate ownership, confidentiality, or branding. It generates a tiled canvas data URL as the overlay's `background-image`, supports text and image watermarks with rotation, gap, offset, and cross-pattern configuration, and includes an optional anti-tamper defense mechanism that automatically restores the overlay if it is removed or modified via DevTools.

> Note: In addition to `SWatermark`, the headless layer also exports `WatermarkCompact` for the default root/overlay structure, plus `WatermarkRoot`, `WatermarkOverlay`, and `provideWatermarkUi` for fully custom composition and style injection.

## Usage

Usage examples for watermark are rendered on the site.

## Features

- 📝 **Text watermarks** — Render repeating text with configurable font size, family, color, and weight.
- 🖼️ **Image watermarks** — Pass an `image` URL to tile an image pattern; supports `crossOrigin: 'anonymous'` for CORS-enabled sources.
- 🔄 **Rotation** — Rotate watermarks by any angle (default `-22°`).
- 📐 **Gap and offset** — Control tile spacing via `gap: [x, y]` and positioning via `offset: [x, y]`.
- ✖️ **Cross pattern** — Set `cross: true` to render two overlapping watermarks along both diagonals.
- 🛡️ **Anti-tamper defense** — When `defense: true`, `MutationObserver` detects overlay removal or attribute tampering and automatically repairs the overlay by re-rendering it.
- 🖥️ **Fullscreen mode** — Set `fullscreen: true` to fix the overlay to the viewport instead of the parent container.
- 🔧 **Headless composition** — Export `WatermarkRoot` + `WatermarkOverlay` + `WatermarkCompact` for custom layouts; inject styles via `provideWatermarkUi`.
- 🌐 **SSR-safe** — Canvas generation guarded by `typeof window === 'undefined'`; overlay not rendered on server.

## Demos

Interactive demos for watermark are rendered on the site.

## API

Structured API summary generated from build-time component metadata.
- Exported symbols (4): Watermark, WatermarkCompact, WatermarkOverlay, WatermarkRoot.

### Watermark

#### Props
Properties for the SWatermark component.
- `class`: The class attribute for the root element. (type `string | false | Record<string, any> | ClassValue[] | null`; optional)
- `ui`: UI class overrides for each slot. (type `Partial<WatermarkUi>`; optional)
- `fullscreen`: When true, the watermark overlay is fixed to the viewport instead of the parent container. (type `boolean`; default `false`; optional)
- `overlayProps`: Properties forwarded to the overlay element. (type `WatermarkOverlayProps`; optional)
- `content`: The text content of the watermark. (type `string`; optional)
- `image`: The image URL of the watermark. When both content and image are provided, image takes priority. (type `string`; optional)
- `fontSize`: The font size of the watermark text in pixels. (type `number`; default `16`; optional)
- `fontFamily`: The font family of the watermark text. (type `string`; default `'sans-serif'`; optional)
- `fontColor`: The font color of the watermark text. (type `string`; default `'rgba(0, 0, 0, 0.15)'`; optional)
- `fontWeight`: The font weight of the watermark text. (type `string | number`; default `'normal'`; optional)
- `rotate`: The rotation angle of the watermark in degrees. (type `number`; default `-22`; optional)
- `gap`: The gap between watermark tiles in pixels, as [x, y]. (type `[number, number]`; default `[100, 100]`; optional)
- `offset`: The offset of the watermark within each tile in pixels, as [x, y]. (type `[number, number]`; default `[0, 0]`; optional)
- `width`: The width of a single watermark tile in pixels. When not provided, it is calculated automatically based on text dimensions and gap. (type `number`; optional)
- `height`: The height of a single watermark tile in pixels. When not provided, it is calculated automatically based on text dimensions and gap. (type `number`; optional)
- `cross`: When true, renders a diagonal cross pattern with two overlapping watermarks. (type `boolean`; default `false`; optional)
- `defense`: When true, observes and restores the watermark overlay if it is tampered with or removed. (type `boolean`; default `false`; optional)

### WatermarkCompact

#### Props
Properties for the WatermarkCompact component.
- `overlayProps`: Properties forwarded to the overlay element. (type `WatermarkOverlayProps`; optional)
- `content`: The text content of the watermark. (type `string`; optional)
- `image`: The image URL of the watermark. When both content and image are provided, image takes priority. (type `string`; optional)
- `fontSize`: The font size of the watermark text in pixels. (type `number`; default `16`; optional)
- `fontFamily`: The font family of the watermark text. (type `string`; default `'sans-serif'`; optional)
- `fontColor`: The font color of the watermark text. (type `string`; default `'rgba(0, 0, 0, 0.15)'`; optional)
- `fontWeight`: The font weight of the watermark text. (type `string | number`; default `'normal'`; optional)
- `rotate`: The rotation angle of the watermark in degrees. (type `number`; default `-22`; optional)
- `gap`: The gap between watermark tiles in pixels, as [x, y]. (type `[number, number]`; default `[100, 100]`; optional)
- `offset`: The offset of the watermark within each tile in pixels, as [x, y]. (type `[number, number]`; default `[0, 0]`; optional)
- `width`: The width of a single watermark tile in pixels. When not provided, it is calculated automatically based on text dimensions and gap. (type `number`; optional)
- `height`: The height of a single watermark tile in pixels. When not provided, it is calculated automatically based on text dimensions and gap. (type `number`; optional)
- `cross`: When true, renders a diagonal cross pattern with two overlapping watermarks. (type `boolean`; default `false`; optional)
- `defense`: When true, observes and restores the watermark overlay if it is tampered with or removed. (type `boolean`; default `false`; optional)

### WatermarkOverlay

- No documented props, emits, slots, or slot props were available.

### WatermarkRoot

#### Props
Properties for the WatermarkRoot component.
- `content`: The text content of the watermark. (type `string`; optional)
- `image`: The image URL of the watermark. When both content and image are provided, image takes priority. (type `string`; optional)
- `fontSize`: The font size of the watermark text in pixels. (type `number`; default `16`; optional)
- `fontFamily`: The font family of the watermark text. (type `string`; default `'sans-serif'`; optional)
- `fontColor`: The font color of the watermark text. (type `string`; default `'rgba(0, 0, 0, 0.15)'`; optional)
- `fontWeight`: The font weight of the watermark text. (type `string | number`; default `'normal'`; optional)
- `rotate`: The rotation angle of the watermark in degrees. (type `number`; default `-22`; optional)
- `gap`: The gap between watermark tiles in pixels, as [x, y]. (type `[number, number]`; default `[100, 100]`; optional)
- `offset`: The offset of the watermark within each tile in pixels, as [x, y]. (type `[number, number]`; default `[0, 0]`; optional)
- `width`: The width of a single watermark tile in pixels. When not provided, it is calculated automatically based on text dimensions and gap. (type `number`; optional)
- `height`: The height of a single watermark tile in pixels. When not provided, it is calculated automatically based on text dimensions and gap. (type `number`; optional)
- `cross`: When true, renders a diagonal cross pattern with two overlapping watermarks. (type `boolean`; default `false`; optional)
- `defense`: When true, observes and restores the watermark overlay if it is tampered with or removed. (type `boolean`; default `false`; optional)

## Notes

### Architecture and benchmark differences

`SWatermark` splits into a headless layer that owns canvas generation, overlay state, and defense logic, and a styled layer that owns the `watermarkVariants` `scv()` recipe (root: `relative`, overlay: `absolute inset-0 pointer-events-none bg-repeat`). The headless `WatermarkCompact` composes `WatermarkRoot` + `WatermarkOverlay` and provides the `repairOverlay` function for defense.

| Aspect              | SoybeanUI                                   | Ant Design `Watermark` | Element Plus `Watermark` | MUI Watermark |
| :------------------ | :------------------------------------------ | :--------------------- | :----------------------- | :------------ |
| Architecture        | headless + styled split                     | styled only            | styled only              | styled only   |
| Text watermark      | ✅                                          | ✅                     | ✅                       | ✅            |
| Image watermark     | ✅ `crossOrigin: anonymous`                 | ✅                     | ✅                       | —             |
| Cross pattern       | ✅ `cross` prop                             | —                      | —                        | —             |
| Anti-tamper defense | ✅ `MutationObserver` (removal + attribute) | ✅ `MutationObserver`  | ✅ `MutationObserver`    | —             |
| Fullscreen mode     | ✅ `fullscreen` prop                        | ✅ `inherit`           | ✅ `content` slot        | —             |
| Headless export     | ✅ Root + Overlay + Compact                 | —                      | —                        | —             |
| Gap/offset control  | ✅ `gap` + `offset`                         | ✅ `gap` + `offset`    | ✅ `gap` + `offset`      | ✅ `gap`      |

### Runtime cautions

- **Canvas requirement**: Watermark generation uses `<canvas>` and `canvas.toDataURL()`. In environments without canvas support (e.g., some SSR setups), the overlay will not render — `generateWatermarkDataUrl` returns `undefined`.
- **CORS for images**: Image watermarks use `crossOrigin = 'anonymous'`. The image server must send appropriate CORS headers (`Access-Control-Allow-Origin`), otherwise the canvas becomes tainted and `toDataURL()` throws.
- **Defense is opt-in**: The `defense` prop defaults to `false`. Enable it with `defense: true` to activate `MutationObserver`-based tamper detection. Defense has a small performance cost due to observer callbacks.
- **Defense scope**: The defense mechanism detects overlay removal (via root's `childList` observer) and attribute tampering (via overlay's `attributes` observer). It checks `aria-hidden`, `class`, `style`, `hidden`, and `data-soybean-watermark-overlay` attribute. If any is modified, the overlay is re-rendered via a `:key` increment.
- **`fullscreen` positioning**: When `fullscreen: true`, the overlay switches from `absolute inset-0` (parent-relative) to `fixed inset-0 z-9999` (viewport-fixed), covering the entire screen.

### Headless Composition

When the default root/overlay structure is enough, import `WatermarkCompact` from `@soybeanjs/headless/watermark`. If you need separate control over the root and overlay elements, compose the headless primitives directly:

```vue
<script setup lang="ts">
import { computed } from 'vue';
import { WatermarkOverlay, WatermarkRoot, provideWatermarkUi } from '@soybeanjs/headless';

const ui = computed(() => ({
  root: 'relative',
  overlay: 'absolute inset-0 pointer-events-none bg-repeat'
}));

provideWatermarkUi(ui);
</script>

<template>
  <WatermarkRoot content="CONFIDENTIAL" :rotate="-22">
    <slot />
    <WatermarkOverlay />
  </WatermarkRoot>
</template>
```

### FAQ

**How do I add a watermark to the entire page?**
Set `fullscreen: true`: `<SWatermark content="CONFIDENTIAL" fullscreen />`. The overlay switches to `fixed inset-0 z-9999`, covering the viewport.

**How do I prevent users from removing the watermark via DevTools?**
Enable defense: `<SWatermark content="CONFIDENTIAL" defense />`. The component uses `MutationObserver` to detect overlay removal or attribute tampering and automatically re-renders the overlay. Note that this is not foolproof — determined users can still disable JavaScript or block observers.

**Can I use an image as the watermark pattern?**
Yes. Pass the `image` prop: `<SWatermark image="/logo.png" />`. The image is loaded with `crossOrigin = 'anonymous'`, so the server must send CORS headers. When both `content` and `image` are provided, `image` takes priority.

**What is the `cross` pattern?**
Set `cross: true` to render two overlapping watermarks — one along the main diagonal and one along the anti-diagonal with opposite rotation. This creates a denser, cross-shaped pattern.

**How do I control the tile spacing?**
Use the `gap` prop: `<SWatermark content="DRAFT" :gap="[200, 150]" />`. The first value is horizontal spacing, the second is vertical. Use `offset` to shift the watermark within each tile.

## Headless

- Page URL: /headless
- Markdown URL: /headless.md
- Description: Unstyled, fully accessible component logic — the foundation @soybeanjs/ui is built on.

# Headless

> Unstyled, fully accessible component logic — the foundation `@soybeanjs/ui` is built on.

`@soybeanjs/headless` is the logic layer of SoybeanUI. State, keyboard interaction, focus management and accessibility semantics live here, with zero visual styling. The styled components in `@soybeanjs/ui` are thin wrappers on top of it.

## Installation

```bash
pnpm add @soybeanjs/headless
```

## Layer split

| Layer  | Package               | Owns                                                 |
| ------ | --------------------- | ---------------------------------------------------- |
| Logic  | `@soybeanjs/headless` | State, a11y, keyboard navigation, focus, zero styles |
| Styled | `@soybeanjs/ui`       | UnoCSS variants, class injection, slot forwarding    |

The compile-time dependency direction is **UI → Headless**. Headless never imports UI.

## Exports

- `.` — every component and type
- `./composables` — 28 reusable composables (`useControllableState`, `useContext`, `useUiContext`, …)
- `./shared` — pure TypeScript utilities (DOM, focus, tree, form, guard, comparison)
- `./types` — shared types such as `ClassValue`, `UiClass` and `ToContext`
- `./date`, `./locale`, `./constants`
- `./nuxt` and `./resolver` — Nuxt auto-registration and the `unplugin-vue-components` resolver
- `./namespaced` — namespace export (for example `Headless.AccordionRoot`)
- `./<component>` — per-component sub-path (for example `@soybeanjs/headless/accordion`)

## Scope

- 96 component directories, 94 of them publicly exported
- 28 composables and 20 pure-utility modules

`@soybeanjs/headless` ships no styles at all — not even `hidden` or `sr-only`. Layout-contract geometry is the only structural output, and presentation belongs to the styled layer.

## Installation

- Page URL: /overview/installation
- Markdown URL: /overview/installation.md
- Description: SoybeanUI offers two ways to add components to your project. Choose the one that fits your workflow.

# Installation

SoybeanUI offers two ways to add components to your project. Choose the one that fits your workflow.

## Comparison

|                   | npm Package                             | CLI (sbean)                                          |
| ----------------- | --------------------------------------- | ---------------------------------------------------- |
| **How it works**  | Install `@soybeanjs/ui` as a dependency | Copy source code into your project                   |
| **Customization** | Configure via props and CSS variables   | Full source control — edit any file                  |
| **Updates**       | `pnpm update` pulls latest              | `sbean diff` shows changes, you choose what to merge |
| **Bundle size**   | Tree-shaking removes unused components  | Only the components you add exist in your project    |
| **Best for**      | Quick prototyping, standard setups      | Custom design systems, full control                  |
| **Setup**         | `pnpm add @soybeanjs/ui`                | `npx sbean init && npx sbean add button`             |

## npm Package (Recommended for most projects)

Install the styled component library with a single command:

```bash
pnpm add @soybeanjs/ui
```

Import styles:

```ts
import '@soybeanjs/ui/styles.css';
```

Import components directly from the package:

```vue
<script setup lang="ts">
import { SButton } from '@soybeanjs/ui';
</script>

<template>
  <SButton>Click me</SButton>
</template>
```

### Optional: Auto-import with unplugin-vue-components

```ts
// vite.config.ts
import Components from 'unplugin-vue-components/vite';
import UiResolver from '@soybeanjs/ui/resolver';

export default defineConfig({
  plugins: [
    Components({
      resolvers: [UiResolver()]
    })
  ]
});
```

Now you can use components without importing them:

```vue
<template>
  <SButton>Click me</SButton>
  
</template>
```

## CLI — Copy-Paste (shadcn-style)

Prefer full control over your component source code? Use the `sbean` CLI to copy components directly into your project.

### 1. Initialize

```bash
npx sbean init
```

This creates an `sbean.json` config file and sets up UnoCSS with the correct aliases.

### 2. Add Components

```bash
npx sbean add button
```

The component source files are copied to your project:

```
src/ui/
├── components/
│   └── button/
│       ├── button.vue
│       ├── index.ts
│       └── types.ts
├── styles/
│   └── button.ts
└── theme/
    └── index.ts
```

### 3. Use Components

All components use the `#ui` import alias:

```vue
<script setup lang="ts">
import SButton from '#ui/components/button';
</script>
```

### 4. Update Components

```bash
# See what changed
npx sbean diff button

# Update to latest
npx sbean add button --overwrite
```

### CLI Reference

See the [CLI documentation](/sbean) for a complete command reference.

## Next Steps

- [Quick Start](/overview/quick-start) — set up your project from scratch
- [Theming](/overview/theming) — customize colors, fonts, and sizes
- [Components](/components) — browse all available components

## Introduction

- Page URL: /overview/introduction
- Markdown URL: /overview/introduction.md
- Description: SoybeanUI is an elegant, modern, accessible, and high-quality UI component system designed for Vue 3. It supports two distribution modes — install as a traditional npm package, or copy source code directly into your project via the sbean CLI (shadcn-style). Built on a powerful Headless foundation, it provides a comprehensive set of accessible, customizable, and high-performance components to help developers build modern web applications quickly.

# Introduction

SoybeanUI is an elegant, modern, accessible, and high-quality UI component system designed for Vue 3. It supports **two distribution modes** — install as a traditional npm package, or copy source code directly into your project via the `sbean` CLI (shadcn-style). Built on a powerful Headless foundation, it provides a comprehensive set of accessible, customizable, and high-performance components to help developers build modern web applications quickly.

## Two Ways to Use SoybeanUI

SoybeanUI gives you the freedom to choose how components live in your project:

### npm Package — Quick Integration

Install `@soybeanjs/ui` as a dependency and get started in minutes. Auto-import with `unplugin-vue-components`, tree-shaking, and seamless updates via your package manager. This is the recommended path for most projects.

```bash
pnpm add @soybeanjs/ui
```

### CLI · Copy-Paste — Full Source Control

Prefer owning the source code? Use `sbean` CLI to copy components directly into your project. Edit any file, customize anything — the code is yours. Pull upstream updates with `sbean diff` when you want them.

```bash
npx sbean init
npx sbean add button
```

See the [Installation](/overview/installation) guide for a detailed comparison, or jump directly to the [CLI documentation](/sbean).

## Why SoybeanUI?

### 🎨 Elegant design

SoybeanUI adopts a modern design language with polished visuals and smooth interactions. Every component is carefully crafted to deliver an excellent user experience across different scenarios.

### ♿ Accessibility first

All components strictly follow WAI-ARIA design patterns, ensuring they are easy to use for everyone, including users with disabilities. Accessibility features such as keyboard navigation, screen reader support, focus management, and RTL-aware direction support are built in—no extra wiring required beyond configuration.

### 🏗️ Flexible architecture

SoybeanUI uses a Headless architecture that fully separates logic from presentation. This means you can:

- **Use pre-styled components**: use `@soybeanjs/ui` out of the box
- **Bring your own styles**: use `@soybeanjs/headless` to build your own design system
- **Mix and match**: use both approaches in the same project

### 🎯 Type safety

Built entirely with TypeScript, SoybeanUI provides complete type definitions and smart IntelliSense to make development more efficient and reliable.

### 🎨 Highly customizable

Built on UnoCSS and `@soybeanjs/cva`, SoybeanUI supports flexible theming. You can easily adjust colors, sizes, border radius, and more to match your brand.

### 📦 Lightweight

All components support tree-shaking, so you only bundle what you actually use—keeping your final build as small as possible.

## Architecture

SoybeanUI's component runtime uses a strict **two-layer separation**. The
arrows below mean “depends on”:

```
Consumer ──> @soybeanjs/ui ──> @soybeanjs/headless
                    │
                    └───────> @soybeanjs/theme

UnoCSS config ──> @soybeanjs/ui-uno
                    └───────> @soybeanjs/theme
```

The compile-time dependency is one-way: `@soybeanjs/ui` imports public
`@soybeanjs/headless` entry points, while headless never imports UI. At runtime,
styled wrappers inject slot class maps through `provideXUi(computedUi)`, and the
wrapped headless parts read them through `useUiContext()`.

### @soybeanjs/headless - Logic layer

This is the core foundation of SoybeanUI, responsible for handling all component logic:

- **State management**: complete internal state management
- **Accessibility (A11y)**: full WAI-ARIA support
- **Keyboard interactions**: comprehensive keyboard navigation
- **Focus management**: intelligent focus trapping and restoration
- **Event handling**: a unified event handling mechanism
- **Compact aggregators**: ready-to-use aggregated components for data-driven scenarios

Headless components ship no visual theme, giving you maximum freedom to build
your own design system. Behavior-critical CSS variables or inline layout values
may still be used for positioning and interaction. If you want full control
over the look and feel—or need a unique design system—`@soybeanjs/headless` is
the best choice.

### @soybeanjs/ui - Presentation layer

This is the styled component library built on top of Headless:

- **Beautiful styling**: modern styles built with UnoCSS and `@soybeanjs/cva`
- **Ready to use**: works out of the box with minimal setup
- **Theme support**: built-in theme presets, including light/dark mode
- **Responsive design**: optimized for different screen sizes
- **Flexible customization**: override any slot's style classes via the `ui` prop

If you want to get started quickly or prefer SoybeanUI's default look, `@soybeanjs/ui` is the recommended choice.

### Component Patterns

SoybeanUI supports three component patterns:

#### 1. Multi-slot Base Components

For complex components that need fine-grained control over each part (like Accordion, Dialog, Card):

- Headless exposes multiple primitive components (Root, Trigger, Content, etc.)
- Uses `UiSlot` + `UiClass` to define style slots
- UI layer injects styles via `provide{Name}Ui(ui)`

#### 2. Compact Aggregators

For data-driven scenarios with stable structures (like lists, tables, form groups):

- Headless handles data iteration, default content, and structure composition
- Exposes `{Name}Compact` component with corresponding Props/Emits/Slots types
- UI wrapper focuses on style variants and prop/slot forwarding
- Examples: `AccordionCompact`, `TableCompact`, `CheckboxGroupCompact`

When you have a stable data list to render, Compact components let you accomplish the task with more concise code.

#### 3. Single-class Components

For simple atomic components (like Button, Link, Badge):

- No UiContext
- UI layer directly uses `{name}Variants({...}, props.class)` to merge styles

## Key features

### ✨ Rich component ecosystem

SoybeanUI provides more than 80 high-quality components covering most common web application scenarios:

- **Basic**: Button, Input, Card, Badge, etc.
- **Forms**: Form, Select, Checkbox, RadioGroup, Switch, etc.
- **Feedback**: Alert, Dialog, Toast, Tooltip, etc.
- **Navigation**: Menu, Tabs, Breadcrumb, Pagination, etc.
- **Data display**: Table, Tree, List, Avatar, etc.
- **Layout**: Layout, Separator, AspectRatio, etc.

### 🎨 Theme system

SoybeanUI includes a powerful theme system that supports:

- **8 semantic colors**: `primary` · `destructive` · `success` · `warning` · `info` · `carbon` · `secondary` · `accent`
- **6 sizes**: `xs` · `sm` · `md` · `lg` · `xl` · `2xl` (base `md` = 16px)
- **Multiple variants**: `solid`, `outline`, `ghost`, `link`, `plain`, `dashed`, `soft`, `raw`
- **Dark mode**: full dark theme support
- **RTL direction**: switch supported components between LTR and RTL layouts with `ConfigProvider.dir`
- **ConfigProvider**: unified configuration for `dir`, `locale`, `nonce`, and global tooltip options

### 🚀 Performance

- **Tree-shaking**: bundle only what you use
- **On-demand imports**: supports importing components as needed
- **Virtual scrolling**: optimized for large data sets
- **Lazy loading**: lazy-load images and content when appropriate

### 🔧 Developer experience

- **TypeScript**: complete type definitions
- **Auto import**: supports auto-import with `unplugin-vue-components`
- **Nuxt module**: official Nuxt module support
- **Detailed docs**: each component includes comprehensive docs and examples

## Use cases

SoybeanUI works well for many types of Vue 3 projects:

- **Enterprise apps**: complete ecosystem with strong accessibility
- **Admin dashboards**: rich form and data display components
- **Content sites**: elegant display components and layout system
- **Mobile-friendly apps**: responsive design for various screen sizes
- **Design systems**: Headless architecture for building custom systems

## Tech stack

SoybeanUI is built with:

- **Vue 3**: Composition API and `<script setup>`
- **TypeScript**: full type support
- **UnoCSS**: atomic CSS engine
- **@soybeanjs/cva**: variant recipe management

## Getting started

If you’re ready to start using SoybeanUI, check out the [Quick Start](./quick-start) guide to learn how to install and configure it.

If you want to learn more about specific components, browse the [Component docs](/components/button) for detailed APIs and examples.

## Community & support

- **GitHub**: [soybeanjs/soybean-ui](https://github.com/soybeanjs/soybean-ui)
- **Issues**: feel free to report problems via GitHub Issues
- **Feature requests**: pull requests are welcome

Let’s build a better Vue 3 UI component library together!

## LLMs.txt

- Page URL: /overview/llms
- Markdown URL: /overview/llms.md
- Description: How to use SoybeanUI's generated LLM-friendly documentation with Cursor, Windsurf, GitHub Copilot, ChatGPT, Claude, and similar AI tools.

# LLMs.txt

> How to use SoybeanUI's generated LLM-friendly documentation with Cursor, Windsurf, GitHub Copilot, ChatGPT, Claude, and similar AI tools.

## What is LLMs.txt?

LLMs.txt is a structured documentation format for large language models. SoybeanUI generates dedicated LLM-friendly files during the docs build so AI tools can consume the library docs, API details, and usage guidance more reliably than by reading the rendered website alone.

The generated files are optimized for AI consumption and currently use the English docs set as the source of truth.

## Available routes

SoybeanUI exposes the following LLM-oriented routes from the docs build output:

- **/llms.txt** - a compact overview of the docs and component links, intended for normal context windows
- **/llms-full.txt** - a much larger bundle that includes the rendered documentation content plus generated API details
- **/overview/\*.md** and **/components/\*.md** - page-level Markdown routes for individual English guide and component pages

## Choosing the right file

> Start with **/llms.txt** in most cases. It is smaller, faster to load into AI context, and usually enough for general guidance and navigation.

Use **/llms-full.txt** when you need:

- richer component API details
- rendered guide content in one place
- a larger context source for long-form implementation help

Use the per-page Markdown routes when you want to keep prompts narrow, for example only one component or one guide.

## Important notes

- The generated LLM files are based on the English docs source.
- The website itself is localized, but the LLM export currently uses the English documentation source.
- Component API sections in the LLM files are rendered from generated API metadata during the docs build.

## Usage with AI tools

### Cursor

You can reference SoybeanUI docs routes directly in Cursor prompts or add them through docs-based context features.

Examples:

- Use https://ui.soybeanjs.cn/llms.txt as the SoybeanUI docs context
- Follow SoybeanUI component guidance from https://ui.soybeanjs.cn/components/button.md

If you use `@docs`-style references in tools like Cursor or Windsurf, type the trigger manually in the editor UI instead of pasting it.

### Windsurf

Windsurf can use the same routes as persistent documentation references for component usage, theming, and API guidance.

Recommended starting points:

- `/llms.txt` for general usage guidance
- `/llms-full.txt` for deeper API and content coverage
- individual component Markdown routes when you only need one component page

### GitHub Copilot, ChatGPT, Claude, and others

Any tool that can read URLs or pasted Markdown can use these files.

Examples:

- Follow SoybeanUI docs from https://ui.soybeanjs.cn/llms.txt
- Use the Button page from https://ui.soybeanjs.cn/components/button.md
- Use the full SoybeanUI bundle from https://ui.soybeanjs.cn/llms-full.txt

## Practical recommendations

1. Start with `/llms.txt` for quick orientation.
2. Add one or two page-level Markdown routes for the exact guide or component you are working on.
3. Only switch to `/llms-full.txt` when the smaller files are not enough.

## Related routes

- [Quick Start](/overview/quick-start)
- [Introduction](/overview/introduction)
- [Theming](/overview/theming)
- [Components](/components)

## Upgrade Guide v0.40.0

- Page URL: /overview/migration/v0.40.0
- Markdown URL: /overview/migration/v0.40.0.md
- Description: Breaking changes between v0.30.0 and v0.40.0, with before/after migration snippets for the removed peripheral packages, the headless context helpers, and the style-injection cleanup.

# Upgrade Guide: v0.30.0 → v0.40.0

v0.40.0 is a consolidation release: the peripheral packages are retired, the headless layer finally stops injecting styles, and the context helpers are renamed with cleaner semantics. This guide lists every breaking change with a migration path.

## 1. Peripheral packages removed

`@soybeanjs/ui-x`, `@soybeanjs/admin` and `@soybeanjs/chart` are no longer published. They were all released up to `0.30.0`, so if you depend on any of them, pin the old version or migrate as follows.

| Package            | Status                                                                                                                                                             | Where the capability goes                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@soybeanjs/ui-x`  | Removed (20 `Sx*` AI components)                                                                                                                                   | Re-implemented inside `@soybeanjs/headless` + `@soybeanjs/ui` under the standard `S` prefix — see the AI roadmap. Not available yet in `v0.40.0-beta.1`.                                                                    |
| `@soybeanjs/admin` | Removed (skeleton only — no shipped components)                                                                                                                    | Returns as an in-core **shell domain** (`SLayoutShell`, `SPageHeader`, …) — see the shell roadmap. Nothing to migrate.                                                                                                      |
| `@soybeanjs/chart` | Removed (`SChartContainer`, `SChartTooltipContent`, `SChartLegendContent`, `SChartStyle`, `chartColors`, `chartThemes`, `componentToString`, `buildChartColorCss`) | Charts are intentionally **not** part of the core library. The docs site builds its chart demos directly on [TanStack Charts](https://tanstack.com/charts); copy `apps/docs/src/examples/chart/` if you want the same look. |

```bash
# Remove the retired packages
pnpm remove @soybeanjs/ui-x @soybeanjs/admin @soybeanjs/chart
```

```diff
- import { SxBubble, SxSender } from '@soybeanjs/ui-x';
- import { SChartContainer } from '@soybeanjs/chart';
```

If you are not ready to drop them, keep the last published versions pinned:

```json
{
  "dependencies": {
    "@soybeanjs/ui-x": "0.30.0",
    "@soybeanjs/chart": "0.30.0"
  }
}
```

## 2. headless: `RovingFocusGroup` / `RovingFocusItem` components removed

The two SFC primitives are gone from `@soybeanjs/headless` (root export, `./roving-focus` sub-path, and the `Headless.*` namespace). The behaviour now ships as composables, so you own the rendered element:

```diff
- <RovingFocusGroup orientation="horizontal" :loop="true">
-   <RovingFocusItem v-for="tab in tabs" :key="tab" as-child>
-     <button>{{ tab }}</button>
-   </RovingFocusItem>
- </RovingFocusGroup>
+ <script setup lang="ts">
+ import { toContext } from '@soybeanjs/headless/shared';
+ import { useRovingFocusGroup, useRovingFocusGroupItem } from '@soybeanjs/headless/composables';
+
+ const { setContainerElement, groupProps } = useRovingFocusGroup(
+   toContext({ orientation: 'horizontal', loop: true })
+ );
+ </script>
+
+ <template>
+   <div :ref="setContainerElement" v-bind="groupProps">
+     <button v-for="tab in tabs" :key="tab" v-bind="useRovingFocusGroupItem().itemProps">
+       {{ tab }}
+     </button>
+   </div>
+ </template>
```

`useRovingFocusGroup` returns `{ setContainerElement, groupProps, getOrderedItems }` and `useRovingFocusGroupItem` returns `{ setItemElement, itemProps }`. Options are reactive (`ToContext` shape), so build them from props with `toContext(props, [...])`; `itemProps` already carries `tabindex`, the collection attribute, orientation data attributes and the key handlers.

## 3. headless: context helpers renamed with new semantics

```diff
- import type { PropsToContext } from '@soybeanjs/headless/types';
- import { transformPropsToContext } from '@soybeanjs/headless/shared';
+ import type { ToContext } from '@soybeanjs/headless/types';
+ import { fromContext, toContext } from '@soybeanjs/headless/shared';
```

The rename is mechanical, but `toContext` also changed behaviour: `transformPropsToContext` **invoked** function-valued props (`typeof v === 'function' ? v() : v`), while `toContext` stores values as-is, so a function stays a function inside the context.

```ts
// Before: a `renderIcon: () => VNode` prop arrived as the VNode.
// After: it arrives as the function itself.
const context = toContext(props, ['renderIcon']);
context.renderIcon.value(); // call it where it is consumed
```

`fromContext(context, keys)` is the new counterpart: it snapshots a `toContext` map back into plain values, and tolerates a nullish context (useful in `defu` fallback chains).

## 4. headless: `ConfigProviderContext` is now plain values

The context type changed from a computed-per-key map to a readonly snapshot of the props:

```diff
- export interface ConfigProviderContext
-   extends PropsToContext<Omit<ConfigProviderProps, 'iconRender'>>,
-     Pick<ConfigProviderProps, 'iconRender'> {}
+ export type ConfigProviderContext = Readonly<ConfigProviderProps>;
```

If you consumed the context directly, drop the `.value` accessors:

```diff
- const context = useConfigProvider();
- const dir = computed(() => context?.dir?.value ?? 'ltr');
+ const context = useConfigProvider();
+ const dir = computed(() => context?.dir ?? 'ltr');
```

The provider now uses a shared injection key (`Symbol.for('ConfigProvider')`), so a duplicated `@soybeanjs/headless` copy in the module graph no longer breaks the lookup. Direction resolution also gained a step: an explicit `dir` → `ConfigProvider` `dir` → **direction derived from `locale`** → `ltr`.

## 5. headless: no more injected global classes

`SConfigProvider` used to inject a `<style>` tag with helper classes, and several headless parts hard-coded them. Both are gone — headless components are now genuinely style-free:

| Removed class                         | Replacement                               |
| ------------------------------------- | ----------------------------------------- |
| `soybean-headless-scrollbar-hidden`   | `scrollbar-none` (from the UnoCSS preset) |
| `soybean-headless-overflow-y-hidden`  | `overflow-y-hidden`                       |
| `soybean-headless-transition-all-150` | `transition-all duration-150`             |
| `soybean-headless-opacity-0`          | `opacity-0`                               |
| `soybean-headless-scale-0`            | `scale-0`                                 |
| `soybean-headless-sr-only`            | `sr-only`                                 |

The styled wrappers already apply the equivalents (for example `SScrollArea`'s viewport uses `scrollbar-none`), so most users see no change. If you use **headless primitives directly** and relied on the injected CSS, add the classes yourself:

```diff
- <ScrollAreaViewport class="soybean-headless-scrollbar-hidden">
+ <ScrollAreaViewport class="scrollbar-none">
```

Scrollbars are now hidden by a `scrollbar-none` utility shipped from `@soybeanjs/ui-uno` (`presetScrollbar`), which is part of `presetUi()` by default. If you consume headless without the preset, provide your own rule.

## 6. ui: `STable` no longer rounds by default

```diff
- <STable :data="rows" />          {/* was rounded */}
+ <STable :data="rows" rounded />  {/* opt back in */}
```

`rounded` now defaults to `false`, matching the other surface components where rounding is opt-in.

## 7. `@soybeanjs/ui-uno`: animation preset replaced

`unocss-preset-animations` is no longer a dependency; the preset is now built in and exported directly:

```diff
- import UnocssPresetAnimations from 'unocss-preset-animations';
- export default defineConfig({ presets: [presetUi(), UnocssPresetAnimations()] });
+ import { presetAnimations, presetScrollbar } from '@soybeanjs/ui-uno';
+ export default defineConfig({ presets: [presetUi()] }); // both already included
```

`presetUi()` keeps the same signature but gained pass-through options — `wind3`, `animations`, `scrollbar`, `webFonts`, `preflights` — and now also exports `buildGlobalCss`, `buildThemeColors` and `resolveWind3Dark`. A new `presetScrollbar` (which provides `scrollbar-none`, see section 5) is included by default. The `UiUnocssOptions` / `SbeanPresetOptions` types are still exported, so existing configs keep working.

## 8. Dependency cleanup (usually invisible)

- `@nuxt/kit` and `@nuxt/schema` are no longer `peerDependencies` of `@soybeanjs/headless`; the Nuxt module wiring was localised.
- Eleven runtime dependencies were inlined or dropped from `@soybeanjs/headless` (`@soybeanjs/hooks`, `@soybeanjs/utils`, `defu`, `klona`, `fuse.js`, `ohash`, `aria-hidden`, `@floating-ui/utils`, `@vueuse/shared`, `@dnd-kit/helpers`, `embla-carousel-reactive-utils`). If your app imported any of them **without declaring them** (relying on hoisting), add them to your own `package.json`.
- Contributor-side only: `packages/_shared` was renamed to `packages/shared` and switched to source distribution (`#shared/*` sub-path imports).

## What you gain

- **Popper rebuilt in place.** The positioning primitives gained `PopperTrigger`, `PopperPortal`, `PopperSub` / `PopperSubTrigger`, `PopperCompact`, delay groups and `useVirtualPointReference`, all under the existing `Popper*` names — no import changes for the old root/anchor/positioner/popup/arrow parts.
- **New navigation components**: `SNavMenu`, `SSplitNav`, `STreeNav` (plus their headless counterparts).
- **Flash-free persisted theme**: `createThemeInitScript({ injectCss: true })` replays the derived CSS from `THEME_CSS_STORAGE_KEY` before first paint.
- **Router-aware links**: `SConfigProvider` gained `linkComponent`, so every `SLink` / `SButtonLink` can render through `RouterLink` / `NuxtLink` without per-call props.

## Checklist

1. `pnpm remove @soybeanjs/ui-x @soybeanjs/admin @soybeanjs/chart` (or pin to `0.30.0`).
2. Rename `PropsToContext` → `ToContext` and `transformPropsToContext` → `toContext`; review function-valued context keys.
3. Replace `RovingFocusGroup` / `RovingFocusItem` usage with the composables.
4. Drop `.value` accessors on `ConfigProviderContext` consumers.
5. If you use headless primitives directly, replace the `soybean-headless-*` classes.
6. Add `rounded` to `STable` where the rounded look is expected.
7. Remove `unocss-preset-animations` from your UnoCSS config.
8. Declare any previously hoisted transitive dependency you imported directly.

## Upgrade Guide v0.50.0

- Page URL: /overview/migration/v0.50.0
- Markdown URL: /overview/migration/v0.50.0.md
- Description: Breaking changes from v0.40.0 to v0.50.0 — the date engine moves to date-fns + Date, Table/Form move to TanStack, NavigationMenu is removed, Sheet/Drawer are renamed, SPagination's actionAsSelected prop becomes actionVariant, and headless anatomy shells are trimmed — each with a migration mapping.

# Upgrade Guide: v0.40.0 → v0.50.0

v0.50.0 is an engine-level rebuild: the **date, table and form engines are all replaced**, the Sheet/Drawer families swap names by semantics, and headless trims its presentation-only shells. Minors may break during 0.x, and this release ships no compatibility layer — every change gets a migration mapping below.

| Three things you want to know first                                                                    |
| ------------------------------------------------------------------------------------------------------ |
| 1. The date value model is now the native `Date`; `CalendarDate` / `ZonedDateTime` are gone            |
| 2. Table columns and state use TanStack naming as the first citizen — legacy fields get **no aliases** |
| 3. Apps that only consume `@soybeanjs/ui` (`S` components) mostly just need the renames                |

## 1. Date engine: `@internationalized/date` → `date-fns` + `Date`

`@internationalized/date` and `@internationalized/number` are replaced by `date-fns` plus the platform `Intl` APIs. The public value model becomes the native `Date`; component props/slots stay compatible and only the value types change. The first release supports **local dates only** (`ZonedDateTime`, non-Gregorian calendars and `timeZoneName` segments are removed; `hideTimeZone` stays as a no-op for one release cycle).

| v0.40.x                                    | v0.50.0                                                 |
| ------------------------------------------ | ------------------------------------------------------- |
| `CalendarDate` (calendar day)              | `Date` at local midnight                                |
| `CalendarDateTime` (date + time)           | `{ date: Date, time?: Date }`                           |
| `Time` (time of day)                       | `Date` (only h/m/s matter, normalized to a fixed epoch) |
| `DateRange` / `TimeRange` `{ start, end }` | `{ start: Date \| null, end: Date \| null }`            |
| `DateMatcher` / `TimeMatcher`              | `(date: Date) => boolean` predicates                    |

```diff
- import { CalendarDate, CalendarDateTime, Time } from '@internationalized/date';
- const day = new CalendarDate(2026, 4, 19);
- const time = new Time(9, 30);
+ import { createDate, createTime } from '@soybeanjs/headless/date';
+ const day = createDate(2026, 4, 19); // local midnight, month is 1-based
+ const time = createTime(9, 30);
```

Exported type names (`DateValue`, `DateRange`, `TimeValue`…) are unchanged — only their shapes became `Date`. Calendar math moves to `date-fns` functions (`addDays` / `addMonths`…) or the kernel helpers from `@soybeanjs/headless/date` (`setSegmentParts` / `cycleSegment` / `toISODateString`), and number formatting moves to `createNumberFormatter` / `createNumberParser` from `shared` (thin `Intl.NumberFormat` wrappers).

```bash
pnpm remove @internationalized/date @internationalized/number
pnpm add date-fns
```

The full operation / formatting / parsing mapping lives in the dedicated guide: **[Date engine migration](/overview/migration/v0.50.0-date)**.

## 2. Table engine: `@tanstack/vue-table`

The hand-rolled column model (sorting / filtering / expanding / pinning / sizing) is replaced by [`@tanstack/vue-table`](https://tanstack.com/table) v9. TanStack naming is the first citizen and legacy fields get **no aliases** (a deliberate design decision) — rename them by hand:

| v0.4x (legacy)                            | v0.50.0 (TanStack)                                                 |
| ----------------------------------------- | ------------------------------------------------------------------ |
| `{ title, dataIndex }`                    | `{ header, accessorKey }`                                          |
| `sorter: true` / `sorter(a, b)`           | `enableSorting: true` / `sortFn: (rowA, rowB) => number`           |
| `filter: true` / `filter: { ... }`        | `enableColumnFilter: true` / `filterPlaceholder` / `filterOptions` |
| `width: '140px'` / `minWidth`             | `size: 140` / `minSize` (px numbers)                               |
| group column `{ key, children }`          | `{ id, columns }`                                                  |
| `sortState` / `defaultSortState`          | `sorting` / `defaultSorting` (`SortingState`)                      |
| `filterState` / `defaultFilterState`      | `columnFilters` / `defaultColumnFilters` (`ColumnFiltersState`)    |
| `columnWidths` / `defaultColumnWidths`    | `columnSizing` / `defaultColumnSizing` (`Record<string, number>`)  |
| `expanded: R[]`                           | `expanded: ExpandedState` (`{ '1': true }` or `true`)              |
| `update:sortState` / `update:filterState` | `update:sorting` / `update:columnFilters`                          |

```diff
  const columns = [
-   { title: 'Name', dataIndex: 'name', sorter: true, width: '180px' },
+   { header: 'Name', accessorKey: 'name', enableSorting: true, size: 180 }
  ];
- const expanded = ref([1]);
+ const expanded = ref({ 1: true });
```

The engine instance is not hidden: slot props carry `table` / `engineColumn`, subtrees can call `useTableEngine()`, the template ref exposes the engine directly (`tableRef.value.previousPage()`), and advanced TanStack options pass through `tableOptions`.

The full field mapping with examples lives in [the Table docs "Migration from v0.4x"](/components/table).

## 3. Form engine: `@tanstack/vue-form`

The self-built `useHeadlessForm` is replaced by [`@tanstack/vue-form`](https://tanstack.com/form). **The component face is unchanged** — `SForm` / `SFormField` / `SFormFieldArray` / `SFormFieldBase` plus the label/description/error and `aria-invalid` / `aria-describedby` wiring all stay. The changes concentrate on the hook face:

| v0.4x                                           | v0.50.0                                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `useForm(options, Field, FieldArray)` tuple     | `useForm(options)` returns a context object (`handleSubmit`, `SFormField`, `isSubmitting`, `form`…) |
| `initialValues`                                 | `defaultValues` (TanStack naming)                                                                   |
| `onSubmit(values, helper)`                      | `onSubmit(values)` (`FormSubmitHelper` removed)                                                     |
| `formState.values` / `errors` `state` snapshot  | `form.useSelector(state => …)` / `form.Subscribe` (the raw `form.state` remains on `FormApi`)       |
| `reValidateMode` / field-level `reset` callback | Removed — set `validateMode: 'change'` for live validation; reset restores `defaultValues`          |
| Nested array path `social.0.name`               | TanStack canonical `social[0].name` (error paths use brackets too)                                  |

Validation accepts a Standard Schema object directly (Zod / Valibot both work); `@standard-schema/spec` is no longer a direct dependency of the library — your own validation library provides it. Field-level `validate` accepts a function or a Standard Schema validator, and passing it through a `Ref` rebinds rules reactively.

The complete hook-face mapping and caveats (array error paths, the `_form` key, `formOptions` passthrough) live in [the Form docs "Migration from v0.4x"](/components/form).

## 4. NavigationMenu removed

`SNavigationMenu` and the whole `navigation-menu` family (headless sub-path, root exports, the `Headless.*` namespace, the registry entry) are removed; `nav-menu` is the only navigation menu family:

```diff
- import { SNavigationMenu } from '@soybeanjs/ui';
+ import { SNavMenu } from '@soybeanjs/ui';

- import { NavigationMenuRoot } from '@soybeanjs/headless/navigation-menu';
+ import { NavMenuRoot } from '@soybeanjs/headless/nav-menu';
```

Root props are nearly isomorphic; sub-menu flyouts move from "indicator + viewport" to nested popovers beside the item (`NavMenuSubTrigger` / `NavMenuSubContent`), and mount control switches from `unmountOnHide` to `forceMount` on the content primitives. The full mapping lives in [the migration notes](/components/navigation-menu) (kept for one release cycle) and [the NavMenu docs](/components/nav-menu).

## 5. Sheet / Drawer renames

Two families swap names so the semantics are explicit: side panels are Sheet, gesture drawers are Drawer.

**`SDrawer` (side panel) → `SSheet`** — still composed from the Dialog primitives, behavior is identical, a pure rename:

| Legacy                                        | New                                        |
| --------------------------------------------- | ------------------------------------------ |
| `SDrawer`                                     | `SSheet`                                   |
| `drawerVariants`                              | `sheetVariants`                            |
| `DrawerProps` / `DrawerEmits` / `DrawerSlots` | `SheetProps` / `SheetEmits` / `SheetSlots` |

**`SBottomSheet` (gesture drawer) → `SDrawer`** — the family renames wholesale, and the kernel is rebuilt on the Base UI model:

| Legacy                                    | New                                                                                                                         |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `SBottomSheet` / `BottomSheetRoot` / `…`  | `SDrawer` / `DrawerRoot` / `…` (prefix maps one-to-one)                                                                     |
| `@soybeanjs/headless/bottom-sheet`        | `@soybeanjs/headless/drawer`                                                                                                |
| `v-model:active-snap-point`               | `v-model:snap-point`                                                                                                        |
| `direction` prop (headless)               | `side` prop                                                                                                                 |
| `data-soybean-bottom-sheet-*`             | `data-soybean-drawer-*`                                                                                                     |
| `shouldScaleBackground` / `fadeFromIndex` | Removed — wrap the page in `DrawerIndent` + `DrawerIndentBackground`; overlay opacity now fades continuously with the swipe |

```diff
- <SBottomSheet v-model:open="open" v-model:active-snap-point="snap" :snap-points="[0.5, 1]">
+ <SDrawer v-model:open="open" v-model:snap-point="snap" :snap-points="[0.5, 1]">
    <template #trigger><SButton>Open</SButton></template>
    Content
- </SBottomSheet>
+ </SDrawer>
```

Note that the `snapPoint` default changed from `null` to the first entry of `snapPoints` (a drawer opens snapped to its first snap point). Rename and engine details live in the [Sheet docs](/components/sheet) and the [Drawer docs](/components/drawer).

## 6. headless anatomy shells trimmed (skip if you only use the UI layer)

Presentation-only families are removed from headless; **every `@soybeanjs/ui` component name survives** — only projects importing headless primitives directly are affected:

| Removed headless sub-path      | Migration                                                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `@soybeanjs/headless/card`     | `SCard` remains (now composed on `CollapsibleRoot`, open by default; recipe and `ui` override semantics unchanged) |
| `@soybeanjs/headless/empty`    | `SEmpty` remains (UI-only implementation)                                                                          |
| `@soybeanjs/headless/list`     | No S counterpart — plain lists use `ul/li` + UI classes; interactive lists use `listbox` / `tree`                  |
| `@soybeanjs/headless/skeleton` | `SSkeleton` remains (UI-only implementation)                                                                       |
| `@soybeanjs/headless/badge`    | `SBadge` remains (UI-only implementation; dismissible via Button/Icon)                                             |
| `@soybeanjs/headless/tag`      | `STag` remains (UI-only implementation); interactive editable tags belong to `tags-input`                          |

The `Alert` family stays in headless and gains the missing semantics: `role?: 'alert' | 'status'` (default `'alert'`; the live region is implied by ARIA) — an addition, not a break.

## 7. `SPopper` / `SArrow` no longer exported from the UI package

The zero-style forwarders are no longer public — `SPopper` wrapped the headless `PopperCompact` plus a style recipe, and `SArrow` re-exported the headless `Arrow`. The styled surface is carried by popover / tooltip / hover-card:

```diff
- import { SPopper, SArrow } from '@soybeanjs/ui';
+ import { PopperCompact } from '@soybeanjs/headless/popper'; // unstyled assembly, positioning styles are on you
+ import { Arrow } from '@soybeanjs/headless/arrow';
```

## 8. Dependency changes

The headless runtime dependencies shrink to a whitelist where only engine-level capabilities may be third-party:

```bash
# Removed (they may have appeared in your lockfile as transitive deps)
@dnd-kit/dom            # PageTabs sorting now uses the self-built useSortableList
@dnd-kit/vue
@formkit/auto-animate   # animations now use the self-built collapseMotion state machine
@internationalized/date # see section 1
@internationalized/number
@standard-schema/spec   # validators come from your own Zod / Valibot

# Added
date-fns                # date engine
@tanstack/vue-table     # table engine
@tanstack/vue-form      # form engine
```

If your code imported any of the removed packages directly (relying on pnpm hoisting), declare them in your own `package.json`. For date-fns prefer sub-path imports (`date-fns/addDays`) so bundlers without sideEffects awareness only load what you use.

On tree-shaking: the bundle built from `import { SButton } from '@soybeanjs/ui'` is now asserted to contain no table / form / date-fns / embla code (the bundle fixture runs in CI), and the headless/ui runtime dependency whitelist is enforced by the `pnpm check:deps` gate.

## 9. `SPagination`: `actionAsSelected` → `actionVariant`

The flag that made the first/prev/next/last buttons adopt the item styling is renamed; semantics and the `false` default are unchanged, and the selected page keeps its `variant` styling either way:

```diff
- <SPagination variant="solid" action-as-selected :total="200" />
+ <SPagination variant="solid" action-variant :total="200" />
```

The styling props themselves (`variant` / `shape` / `size`) are untouched, and the recipe still applies the variant to the action buttons only while the flag is on. See the [Pagination docs](/components/pagination) for the current prop table.

## What you get in return

- **Rebuilt Drawer gesture kernel** (Base UI model): CSS-variable-driven transforms, a snap point value model, a native touch pipeline (touch/scroll arbitration, scroll-edge swipe start), the `DrawerIndent` primitive and nested coordination.
- **Self-built motion**: `useSortableList` for PageTabs sorting (FLIP swaps + keyboard reordering) and the `collapseMotion` height-collapse animation for form errors and tree expansion.
- **Table engine escape hatches**: `useTableEngine()` injection, full `tableOptions` passthrough, and slot props carrying the engine instance.
- **Form expressiveness**: dual-source generic inference for `UseFormOptions` (derive `Values` from `defaultValues` when no schema), field `validate` accepting Standard Schema objects and reactive rebinding.
- **Newly public exports**: `InputNumberClear`, `LayoutPlaceholder`, `MenubarMenus`, `NavMenuOptionCompact`, `TableCompactHead` / `TableCompactRow` / `TableVirtualSpacerRow`.
- **A11y**: the `role="alert" | "status"` semantics on Alert, with inert background marking (`markOthers`) carried over from the previous release.
- **CI quality gates**: the tree-shaking bundle fixture and the dependency whitelist/blacklist check (`pnpm check:deps`).
- The `sbean` CLI moved to `packages/cli` — package name and `bin` are unchanged, invisible to consumers.

## The rebrand is not part of this release

The brand-level rename (SoybeanUI → Vean: the npm scope switch, `@soybeanjs/headless` → `@vean/aria`, `data-soybean-*` → `data-vean-*`, `--soybean-*` → `--vean-*`, the `sbean` CLI → `vean`) has been split out of this window and will ship in a **separate version** with its own upgrade guide and codemod. Everything in this release keeps the `@soybeanjs/*`, `data-soybean-*` and `sbean` names.

Unchanged: the `S` component prefix (= Styled), design tokens `--primary` / `--size` / `--radius`, and `@soybeanjs/cva` / `@soybeanjs/colord`. The theme moved to a single `localStorage` envelope (`__SOYBEAN_THEME`, see the [theming guide](/overview/theming)) and the old `__SOYBEAN_THEME*` keys are no longer read.

## Upgrade checklist

1. `pnpm remove @internationalized/date @internationalized/number && pnpm add date-fns`; build date values with `Date` / `createDate` / `createTime`.
2. Move table columns and state to the TanStack shapes (`accessorKey` / `sorting` / `columnFilters` / `ExpandedState`…); legacy fields have no aliases.
3. Migrate `useForm` to the context-object return face and rename `initialValues` → `defaultValues`.
4. `SNavigationMenu` → `SNavMenu` (and `NavMenu*` in headless).
5. `SDrawer` → `SSheet`; `SBottomSheet` → `SDrawer` (`v-model:active-snap-point` → `v-model:snap-point`, scale background → `DrawerIndent`).
6. Replace direct headless `card` / `empty` / `list` / `skeleton` / `badge` / `tag` imports with the UI components or your own composition.
7. Replace `SPopper` with `PopperCompact` (or migrate to popover / tooltip / hover-card) and import `SArrow` replacements from `@soybeanjs/headless/arrow`.
8. Declare any hoisting-relied removed packages explicitly in your `package.json`.
9. `SPagination`'s `actionAsSelected` prop → `actionVariant` (`:action-as-selected` → `:action-variant`).
10. After `pnpm typecheck` and a build passes, focus regression on date pickers, table sorting/filtering, form validation and drawer gestures.

## Upgrade Guide v0.50.0 — Date Engine

- Page URL: /overview/migration/v0.50.0-date
- Markdown URL: /overview/migration/v0.50.0-date.md
- Description: Migrate from @internationalized/date to the new date-fns + native Date value model — value mapping, helper mapping, formatter/parser replacement, and the range/time-field changes.

# Upgrade Guide: Date engine → `date-fns` + `Date`

v0.50.0 replaces `@internationalized/date` (and `@internationalized/number`) with `date-fns` and the platform `Intl` APIs. The public value model is now plain `Date` objects — there is no `CalendarDate`/`ZonedDateTime` adapter layer. The first release only supports **local dates**; timezone-aware values are out of scope (a separate proposal may follow).

## 1. Value model mapping

| v0.40.x                                              | v0.50.0                                                            |
| ---------------------------------------------------- | ------------------------------------------------------------------ |
| `CalendarDate` (calendar day)                        | `Date` at **local 00:00**                                          |
| `CalendarDateTime` (date + time)                     | `{ date: Date, time: Date }` (`DateTimeValue`)                     |
| `Time` (time of day)                                 | `Date` whose hour/minute/second parts are meaningful (`TimeValue`) |
| `DateRange` `{ start?: DateValue, end?: DateValue }` | `{ start?: DateValue \| null, end?: DateValue \| null }`           |
| `TimeRange` `{ start?: TimeValue, end?: TimeValue }` | `{ start?: Date \| null, end?: Date \| null }`                     |
| `DateMatcher` / `TimeMatcher`                        | `(date: Date) => boolean` / `(time: Date) => boolean`              |

The exported type names (`DateValue`, `DateRange`, `TimeValue`, `TimeRange`, …) are unchanged — only their shapes changed. A plain `Date` is always a valid `DateValue`; the `{ date, time? }` object is required once a time part exists. Time values are normalized onto a fixed local epoch (2000-01-01), so only their time-of-day parts are meaningful.

```diff
- import { CalendarDate, CalendarDateTime, Time } from '@internationalized/date';
- const day = new CalendarDate(2026, 4, 19);
- const dateTime = new CalendarDateTime(2026, 4, 19, 14, 30);
- const time = new Time(9, 30);
+ import { createDate, createTime } from '@soybeanjs/headless/date';
+ const day = createDate(2026, 4, 19);                       // local midnight, 1-based month
+ const dateTime = { date: createDate(2026, 4, 19), time: createTime(14, 30) };
+ const time = createTime(9, 30);
```

Or without helpers: `new Date(2026, 3, 19)` (note `date-fns`-style zero-based month in the native constructor).

## 2. Field value shapes

- `SDateField` / `SDatePicker`: `Date` for day granularity, `{ date, time? }` once a time granularity is used.
- `STimeField`: `Date` (time-of-day only).
- `SCalendarRange` / `SDateRangeField` / `SDateRangePicker`: `{ start, end }` with `null` for empty bounds.
- `STimeRangeField`: `{ start, end }` of time-of-day `Date`s.

```diff
- const range = { start: new CalendarDate(2026, 4, 18), end: undefined };
+ const range = { start: createDate(2026, 4, 18), end: null };
```

## 3. Calendar math and comparison

`@internationalized/date` instance methods are gone. Use `date-fns` functions, the kernel helpers from `@soybeanjs/headless/date`, or native `Date` accessors:

| v0.40.x                              | v0.50.0                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------- |
| `date.add({ days: 1 })`              | `addDays(date, 1)` (date-fns)                                               |
| `date.subtract({ months: 1 })`       | `addMonths(date, -1)`                                                       |
| `date.set({ day: 1, month: 2 })`     | `setSegmentParts(date, { day: 1, month: 2 })` (1-based month, day clamps)   |
| `date.cycle('day', 1)`               | `cycleSegment(date, 'day', 1)`                                              |
| `date.copy()`                        | `cloneDateValue(value)` / `new Date(date.getTime())`                        |
| `date.toString()` (ISO `yyyy-MM-dd`) | `toISODateString(date)`                                                     |
| `date.compare(other)`                | `toDate(a).getTime() - toDate(b).getTime()` or `isBefore`/`isAfter` helpers |
| `isSameDay(a, b)` etc.               | Same names, now exported from `@soybeanjs/headless/date`                    |
| `.day` / `.month` / `.year`          | `date.getDate()` / `date.getMonth() + 1` / `date.getFullYear()`             |

Note the clamping semantics: `setSegmentParts` clamps the day-of-month to the target month length (Jan 31 + `month: 2` → Feb 28), matching the previous behavior, while `addDays`/`addMonths` roll over like `date-fns` always does.

## 4. Formatting and parsing

- `DateFormatter` from `@internationalized/date` → plain `Intl.DateTimeFormat`. The `useDateFormatter(initialLocale, opts)` composable keeps the same method surface (`custom`, `part`, `toParts`, `fullMonth`, …) but all methods take a `Date`.
- `parseDate('2026-04-18')` → `parseISO('2026-04-18')` (date-fns) or `createDate(2026, 4, 18)`.
- `parseDateTime(...)` / `parseZonedDateTime(...)` → `parseISO` / `new Date(...)`. Timezone-prefixed strings are not supported in the first release.
- `NumberFormatter` / `NumberParser` from `@internationalized/number` → `createNumberFormatter(locale, options)` / `createNumberParser(locale, options)` from `@soybeanjs/headless/shared`, both thin wrappers over `Intl.NumberFormat` (`parse` + `isValidPartialNumber` keep their contracts).

## 5. Timezone

`ZonedDateTime`, `CalendarIdentifier`, non-gregorian calendars, `toDate(value, timeZone)` conversions, and the `timeZoneName` segment are removed. `hideTimeZone` stays as a no-op prop for one release cycle. If you need timezone-aware pickers today, convert at your app boundary (e.g. keep UTC `Date`s and offset at display time) — a first-class timezone proposal may follow separately.

## 6. Checklist

date-fns is imported through **subpath modules** (`date-fns/addDays`, `date-fns/isSameDay`, …) rather than the barrel export, so environments without `sideEffects`-aware tree-shaking (webpack 4, CJS SSR, Jest) only load the functions actually used. Follow the same style in your own code:

```bash
# The old packages should be gone from your dependencies
pnpm remove @internationalized/date @internationalized/number
pnpm add date-fns
```

```bash
# No runtime references should remain
grep -rn "@internationalized" src/
# Expect: no output
```

## Quick Start

- Page URL: /overview/quick-start
- Markdown URL: /overview/quick-start.md
- Description: SoybeanUI offers two ways to integrate components into your project. This guide covers both paths — choose the one that fits your workflow.

# Quick Start

SoybeanUI offers two ways to integrate components into your project. This guide covers both paths — choose the one that fits your workflow.

> **Which should I choose?** Use the **npm package** for quick integration with automatic updates. Use the **CLI (sbean)** when you want full control over source code — edit any file, customize anything. See the [Installation](/overview/installation) guide for a detailed comparison.

## Requirements

Before you start, make sure your project meets the following requirements:

- **Node.js** >= 16.0.0
- **Vue** >= 3.3.0
- **Package manager**: pnpm (recommended), npm, or yarn

## Path A: CLI · Copy-Paste (shadcn-style)

Prefer owning your component source code? Use `sbean` to copy components directly into your project.

### 1. Initialize your project

```bash
npx sbean init
```

This creates an `sbean.json` config and sets up UnoCSS. Follow the interactive prompts to choose your colors, font, icon library, and more.

### 2. Add components

```bash
npx sbean add button
npx sbean add dialog select
```

Components are copied to `src/ui/components/` — they're now part of your project. Import them using the `#ui` alias:

```vue
<script setup lang="ts">
import SButton from '#ui/components/button';
</script>

<template>
  <SButton>Click me</SButton>
</template>
```

### 3. Update components

```bash
# See what changed upstream
npx sbean diff button

# Update to the latest version
npx sbean add button --overwrite
```

See the [CLI documentation](/sbean) for all available commands, configuration options, and project structure details.

## Path B: npm Package

If you prefer a traditional dependency workflow, install `@soybeanjs/ui`:

```bash
# pnpm (recommended)
pnpm add @soybeanjs/ui

# or npm
npm install @soybeanjs/ui

# or yarn
yarn add @soybeanjs/ui
```

If you want to build your own design system, install `@soybeanjs/headless`:

```bash
pnpm add @soybeanjs/headless
```

## Path B (continued): Basic setup

### Import styles

If you use `@soybeanjs/ui`, import the stylesheet in your project entry file:

```ts
// main.ts or main.js
import '@soybeanjs/ui/styles.css';
```

## Usage

### Option 1: Auto import (recommended)

Use `unplugin-vue-components` to auto-import components—no manual imports needed.

#### Install dependencies

```bash
pnpm add -D unplugin-vue-components
```

#### Configure Vite

In `vite.config.ts`:

```ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import Components from 'unplugin-vue-components/vite';
import UiResolver from '@soybeanjs/ui/resolver';

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: [UiResolver()]
    })
  ]
});
```

#### Use components

After configuration, you can use SoybeanUI components in any Vue component without importing them manually:

```vue
<template>
  <SButton>Click me</SButton>
  <SInput placeholder="Enter text" />
  <SCard>
    <p>This is a card.</p>
  </SCard>
</template>
```

### Option 2: Manual import

You can also import the components you need manually:

```vue
<script setup>
import { SButton, SInput, SCard } from '@soybeanjs/ui';
</script>

<template>
  <SButton>Click me</SButton>
  <SInput placeholder="Enter text" />
  <SCard>
    <p>This is a card.</p>
  </SCard>
</template>
```

## Nuxt integration

If you use Nuxt 4, you can use the official Nuxt module for simpler configuration.

### Install

```bash
pnpm add @soybeanjs/ui
```

### Configure

Add the module in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  modules: ['@soybeanjs/ui/nuxt']
});
```

After that, you can use all SoybeanUI components in your Nuxt project without additional configuration.

## Using Headless components

If you choose `@soybeanjs/headless`, you'll need to write your own styles. Headless components offer two usage patterns:

### Option 1: Using Base Components (Fine-grained Control)

For scenarios that need complete control over structure and styling:

```vue
<script setup>
import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from '@soybeanjs/headless';
</script>

<template>
  <AccordionRoot>
    <AccordionItem value="item-1">
      <AccordionTrigger>Title</AccordionTrigger>
      <AccordionContent>This is the content area. You can put anything here.</AccordionContent>
    </AccordionItem>
    <AccordionItem value="item-2">
      <AccordionTrigger>Another title</AccordionTrigger>
      <AccordionContent>Another content area.</AccordionContent>
    </AccordionItem>
  </AccordionRoot>
</template>

<style scoped>
/* Add your custom styles here */
</style>
```

### Option 2: Using Compact Components (Data-driven)

For stable structures with data-driven scenarios, offering more concise code:

```vue
<script setup>
import { AccordionCompact } from '@soybeanjs/headless';

const items = [
  {
    value: 'item-1',
    title: 'Title',
    description: 'This is the content area. You can put anything here.'
  },
  {
    value: 'item-2',
    title: 'Another title',
    description: 'Another content area.'
  }
];
</script>

<template>
  <AccordionCompact :items="items" />
</template>

<style scoped>
/* Add your custom styles here */
</style>
```

> Compact components are managed by the headless layer for data iteration and default content rendering, letting you accomplish common tasks with less code.

## Theme configuration

SoybeanUI supports flexible theming. You can configure the global theme using the `ConfigProvider` component:

```vue
<script setup>
import { SConfigProvider } from '@soybeanjs/ui';

const themeConfig = {
  theme: {
    base: 'gray',
    primary: 'indigo',
    radius: '0.625rem'
  },
  size: 'md'
};
</script>

<template>
  <SConfigProvider :theme="themeConfig">
    <YourApp />
  </SConfigProvider>
</template>
```

## RTL configuration

SoybeanUI components support direction switching through `SConfigProvider`. Set `dir="rtl"` at the app root when your product needs right-to-left layouts:

```vue
<template>
  <SConfigProvider dir="rtl">
    <YourApp />
  </SConfigProvider>
</template>
```

For component-level details and configuration boundaries, see the [ConfigProvider documentation](/components/config-provider).

## First example

Let’s create a simple example to verify your installation:

```vue
<template>
  <div class="p-4 space-y-4">
    <h1 class="text-2xl font-bold">SoybeanUI Example</h1>

    <SButton color="primary" @click="handleClick">Click</SButton>

    <SInput v-model="inputValue" placeholder="Enter text" class="w-64" />

    <SCard>
      <template #header>
        <h3>Card title</h3>
      </template>
      <p>This is the card content area.</p>
      <template #footer>
        <SButton size="small">Action</SButton>
      </template>
    </SCard>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const inputValue = ref('');

function handleClick() {
  alert('Button clicked!');
}
</script>
```

## FAQ

### Styles are not applied?

1. Make sure you imported the stylesheet: `import '@soybeanjs/ui/styles.css'`
2. Check the browser console for errors

### TypeScript type errors?

1. Make sure you installed the latest version of `@soybeanjs/ui`
2. Check the type-related configuration in `tsconfig.json`
3. Restart the TypeScript server

### Components are not auto-imported?

1. Make sure `unplugin-vue-components` is configured correctly
2. Verify your `vite.config.ts` configuration
3. Restart the dev server

### Issues when using with Nuxt?

1. Make sure you are using Nuxt 4
2. Verify the module configuration in `nuxt.config.ts`
3. Clear the `.nuxt` cache directory and restart

## Next steps

Now that you’ve installed SoybeanUI, you can:

1. Browse the [Component docs](/components) to see all available components
2. Read the [Theme configuration](../theming) docs to customize theming
3. Visit [GitHub](https://github.com/soybeanjs/soybean-ui) for source code and examples

Enjoy! If you run into any issues, feel free to open an issue on GitHub.

## Skills

- Page URL: /overview/skills
- Markdown URL: /overview/skills.md
- Description: Install SoybeanUI skills to give AI coding agents deep knowledge of components, theming, headless composition patterns, and generated references.

# Skills

> Install SoybeanUI skills to give AI coding agents deep knowledge of components, theming, headless composition patterns, and generated references.

## What are Skills?

Skills are structured knowledge files for AI coding agents. They package library-specific guidance, workflows, and references so an agent can load the right context when a task matches.

Unlike MCP servers, skills do not provide live tools. They provide curated instructions and references directly in the model context.

SoybeanUI currently ships two public skills:

- **soybean-ui** - styled package usage, theming, docs navigation, and generated component references
- **soybean-headless** - headless primitives, Compact patterns, composition guidance, and shared component references

## What the SoybeanUI skills cover

The bundled skills help agents answer tasks such as:

- when to choose `@soybeanjs/ui` versus `@soybeanjs/headless`
- how to set up theming, locale, and direction
- how to use component APIs and generated references efficiently
- how to compose headless primitives into custom-styled wrappers
- how to navigate the docs and generated references without loading the whole site

## Usage

### Skills CLI

The easiest installation path is the `skills` CLI:

```bash
npx skills add soybeanjs/soybean-ui/skills
```

You can target a specific agent:

```bash
npx skills add soybeanjs/soybean-ui/skills --agent cursor
npx skills add soybeanjs/soybean-ui/skills --agent claude-code
```

Or install globally so the skills are available across projects:

```bash
npx skills add soybeanjs/soybean-ui/skills --global
```

Installing the package adds both `soybean-ui` and `soybean-headless`.

### Skills URL

If your tool supports direct skill URLs, you can point it at the public GitHub skill directory.

For the styled UI skill:

```text
https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-ui
```

For the headless skill:

```text
https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-headless
```

### Claude Code

Claude Code can install an individual skill directly from the GitHub directory:

```bash
claude skill add https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-ui
claude skill add https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-headless
```

The repository also ships Claude marketplace metadata inside the published skills package.

### Other AI tools

Any tool that supports GitHub-hosted skill folders or custom instruction directories can use the same sources.

- **SoybeanUI skill entry**: https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-ui/SKILL.md
- **SoybeanUI skill directory**: https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-ui
- **SoybeanHeadless skill entry**: https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-headless/SKILL.md
- **SoybeanHeadless skill directory**: https://github.com/soybeanjs/soybean-ui/tree/main/skills/skills/soybean-headless

## Practical recommendations

1. Install the full `@soybeanjs/ui-skills` package when you work with both styled and headless packages.
2. Use `soybean-ui` when you need component usage, theming, and docs navigation help.
3. Use `soybean-headless` when you need composition guidance or custom-styled wrapper patterns.
4. Keep `llms.txt` as a complementary source when you need docs-wide context instead of packaged skill context.

## Related pages

- [Introduction](/overview/introduction)
- [Quick Start](/overview/quick-start)
- [Theming](/overview/theming)
- [LLMs.txt](/overview/llms)
- [Components](/components)

## Theming

- Page URL: /overview/theming
- Markdown URL: /overview/theming.md
- Description: SoybeanUI ships a three-layer theme engine: a static palette layer, a semantic token layer and a literal layer. Configure it through SConfigProvider, or drive the engine directly when you need the CSS yourself.

# Theming

## Overview

Soybean UI provides a flexible theming system that allows you to customize the appearance of components to match your application's design requirements. You can easily adjust colors, radius and global size settings.

Open the [theme editor](/theme-editor) to change every option against a live gallery of components — the panel there is the same `SThemeCustomizer` an application embeds for its users.

`SThemeCustomizer` takes a `ui` slot map (plus `class`) so a host can restyle the shell: `:ui="{ root: 'w-full h-[70vh]' }"` fills a sidebar instead of using the default fixed box.

## How the theme is built

The theme is **one static palette table plus one dynamic alias table**:

1. **Palette layer** (26 built-in palettes × 11 levels) is emitted as naked channels — `--zinc-100: 240 4.8% 95.9%` — once, and never changes with the theme;
2. **Semantic layer** holds every design token as a _reference_ into that table — `--background: var(--zinc-50)` — and is regenerated on every theme change. A theme switch is a reference swap, not a colour computation;
3. **Literal layer** carries the values that are not colours: dimension (`--size`), the radius ladder (`--radius` … `--radius-4xl`), the spacing grid unit (`--spacing-unit`), layering (`--z-layout` … `--z-max`), line widths and font families.

Token names follow shadcn and are **unprefixed**: `--background`, `--card` / `--popover` (+ `-foreground`), `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive` / `--success` / `--warning` / `--info` (+ `-foreground`), `--border`, `--input`, `--ring`, `--carbon`, `--chart-1` … `--chart-5`, the eight `--sidebar-*` tokens, plus our own `--mask` (the modal scrim, concentration in `--mask-alpha`). Pressed states are no longer separate tokens — compose them with an alpha modifier on the fill (`active:bg-primary/90`).

The palette layer is **static**, which is what keeps a theme switch cheap: the semantic layer only ever swaps references, so switching never recomputes a colour. The engine does **not** measure anything else — every token's level is declared in the token contract, and readability is the theme author's responsibility. `text-2xs`-style utilities, the spacing grid and the radius ladder are all declared values; check your pairs in the [theme editor](/theme-editor) (or with `axe`) rather than relying on the engine to correct them.

A token is consumed as a **channel wrapped in a function**: `hsl(var(--primary) / 0.5)`. Writing the bare `var(--primary)` as a colour silently fails (a channel triple is not a colour). Utility classes (`bg-card`, `text-muted-foreground`, `border-input`) already do the wrapping for you, and are the recommended way; when JavaScript needs the actual colour, use `resolveTokenColor` rather than string-building from the variables.

## Theme configuration

Pass a theme object to `SConfigProvider` at the root of your application:

```vue
<script setup lang="ts">
import { SConfigProvider } from '@soybeanjs/ui';
</script>

<template>
  <SConfigProvider
    :theme="{
      base: 'gray',
      primary: 'violet',
      radius: '0.5rem',
      size: 'md',
      spacing: 'default'
    }"
    persist-theme
  >
    <App />
  </SConfigProvider>
</template>
```

| Option          | Type                                                                               | Default     | What it does                                                                                                     |
| :-------------- | :--------------------------------------------------------------------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------- |
| `base`          | a neutral palette key (`slate` / `mist` / `gray` / `zinc` / `neutral` / `stone` …) | `'zinc'`    | The palette every neutral token reads (surfaces, text, borders).                                                 |
| `primary`       | any palette key (26 built-ins, neutral or chromatic)                               | `'indigo'`  | The brand palette: `primary`, `ring`, `chart-1…5` and the `primary` role ramp follow it.                         |
| `feedback`      | `classic` / `vivid` / `subtle` / `modern` / `professional`                         | `'classic'` | Which palettes back the four status roles (`destructive` / `success` / `warning` / `info`).                      |
| `surfaceStyle`  | `'layered'` / `'flat'`                                                             | `'layered'` | `layered` tints the page so raised surfaces read above it; `flat` keeps every surface at the mode extreme.       |
| `size`          | `xs` / `sm` / `md` / `lg` / `xl` / `2xl`, or a length (`'15px'` / `'0.95rem'`)     | `'md'`      | The root font size — the density knob: every rem-based token scales with it.                                     |
| `radius`        | `2xs` … `2xl`, or a length                                                         | `'md'`      | The radius **seed**: the seven rungs are `calc(var(--radius) * k)`, so changing the seed moves the whole ladder. |
| `spacing`       | `compact` / `default` / `relaxed` / `spacious`, or a multiplier (0 < k ≤ 4)        | `'default'` | The spacing grid unit (`--spacing-unit`): padding, margin and gap utilities are coefficients on it.              |
| `borderOpacity` | number (0 – 1)                                                                     | `1`         | Scales the decorative hairline alpha (`--border-alpha` / `--input-alpha`). Not applied to `--mask-alpha`.        |
| `overrides`     | `{ light?: { [token]: TokenOverride }, dark?: … }`                                 | —           | Per-mode token overrides — the sharpest tool; see below. May include `token.*` refs.                             |
| `preset`        | an inline `{ light, dark }` colour set, or `{ name }` referencing a stored preset  | —           | A reusable colour set; resolved into `overrides` before the engine runs.                                         |
| `prefix`        | `false` / a string                                                                 | `false`     | Namespaces every variable (`--acme-background`). Set it only when the page hosts another design system.          |
| `format`        | `'hsl'` / `'oklch'`                                                                | `'hsl'`     | The palette layer's channel format (the semantic layer only holds references, so it does not care).              |
| `darkSelector`  | `'class'` / `'media'` / a selector                                                 | `'class'`   | How dark mode is expressed in the emitted CSS (`.dark` by default).                                              |
| `styleTarget`   | `'html'` / `':root'`                                                               | `':root'`   | Where the light block is attached.                                                                               |

`SConfigProvider` also takes `persistTheme` (read/write the theme envelope in `localStorage`), `themeConfig` (the envelope injected during SSR), `presetProvider` (resolve a stored preset name on the server), `nonce` and `isServer`.

## Custom color tokens (`overrides`)

`overrides` replaces individual tokens per mode. It has the highest priority — it is applied on top of the derived base / primary / feedback / sidebar tokens (chart colours are derived from `primary` and can be overridden per token too):

```vue
<script setup lang="ts">
import { SConfigProvider } from '@soybeanjs/ui';
</script>

<template>
  <SConfigProvider
    :theme="{
      base: 'gray',
      primary: 'violet',
      radius: '0.5rem',
      overrides: {
        light: {
          background: 'oklch(100% 0 0)',
          foreground: 'stone.950',
          card: 'oklch(100% 0 0)',
          'card-foreground': 'stone.950',
          primary: 'violet.700',
          ring: 'violet.500',
          border: 'stone.200',
          input: 'stone.200'
        },
        dark: {
          background: 'stone.950',
          foreground: 'stone.50',
          card: 'stone.900',
          'card-foreground': 'stone.50',
          primary: 'violet.400',
          ring: 'violet.600',
          border: 'oklch(100% 0 0 / 0.1)',
          input: 'oklch(100% 0 0 / 0.15)'
        }
      }
    }"
  >
    <App />
  </SConfigProvider>
</template>
```

Keys are the **token names** (`background`, `card-foreground`, `sidebar-ring`, …) — the same names the utility classes use, in kebab case. An override value takes one of five forms (the `TokenOverride` type): a palette level reference (`stone.950`), a simple key (`white` / `black`), an `hsl(...)` / `oklch(...)` colour in CSS Color 4 syntax (with an optional `/ <alpha>`), or a **token reference** `token.${name}` (e.g. `ring: 'token.primary'` — the map copies the target token's value at resolve time; colour values land before references). Colour components always carry a `%` — `hsl(238.732 83.529% 66.667%)`, `oklch(60% 0.2 250)` — never the unitless spelling (it must stay the same shape as the palette layer's channels). Raw channel triples (`0 0% 100%`) and hex / `rgb()` are outside the type — the former are format-ambiguous, and for the latter convert first with `colord(...).toHslString()` / `toOklchString()`.

**A complete colour is encoded into the theme format's channels** (a token is consumed as `hsl(var(--soybean-x) / <alpha>)`, so a complete colour would invalidate every declaration): `border: 'oklch(100% 0 0 / 0.1)'` puts the channels into `--border` and the `0.1` into `--border-alpha`. An alpha written into a token that has no companion variable is dropped (use the `/N` utility modifier for transparency). A value that is neither a valid reference nor parseable (`transparent` / `inherit` / an unknown palette / **a self-reference such as `primary: 'token.primary'`** / `token.ghost` / a cyclic `token.*` chain) is **ignored**, and the token keeps its nominal value; so is a key that is not a token — a stale or hand-written key can neither reach the stylesheet nor break it.

**Notes and caveats:**

- **Light and dark are independent.** An override applies to the mode you put it in: `dark` keeps its own declared levels rather than being derived from `light`. Write both sides when you want both.
- **An override is applied verbatim.** It is not measured, corrected or reported — the engine has no opinion about readability (nothing walks a level on your behalf since decision #26).
- **Overrides are per token, not per role.** To recolour the whole brand, change `primary` (the palette) rather than every token that reads it.
- **The engine is a pure function.** Nothing here touches the DOM: the provider resolves the map, emits the alias block and patches its own `<style id="soybean-theme">`.

## Saved presets (`theme.preset`)

A preset is a named colour set a user can re-apply — the theme customizer saves them into the theme envelope. Pass one inline, or reference a stored one by name:

```vue
<template>
  <SConfigProvider
    :theme="{
      base: 'gray',
      primary: 'violet',
      preset: { name: 'midnight' }
    }"
    persist-theme
  >
    <App />
  </SConfigProvider>
</template>
```

An inline preset is just an `overrides` object split by mode (`preset: { light: { … }, dark: { … } }`) and is always honoured. A `{ name }` reference is resolved against the presets carried by the theme envelope — which requires `persistTheme` on the client, and `presetProvider` (an app-level registry resolver) on the server, so SSR renders the same colours the client persisted. A name that cannot be resolved falls back to the built-in colours.

## Using the engine directly

The provider is the normal path — it owns the `<style>` element, the persisted envelope and the cross-tab sync. When you need the CSS yourself (an SSR pass, a static build, a screenshot service), the pipeline underneath is public:

```ts
import { emitThemeCss, generatePaletteCss, resolveThemeMap, resolveTokenColor } from '@soybeanjs/theme';
import { buildThemeCss } from '@soybeanjs/ui';

// resolve + emit in one call (what SConfigProvider inlines)
const css = buildThemeCss({ base: 'gray', primary: 'violet' });

// or step by step: the map is the single intermediate representation
const map = resolveThemeMap({ base: 'gray', primary: 'violet' });
emitThemeCss(map); // Layer 2 — the alias block, regenerated per theme
generatePaletteCss(); // Layer 1 — the static palette table, ship it once

// JavaScript that needs a colour value (a canvas, a chart library)
resolveTokenColor({ primary: 'violet' }, 'primary', 'dark'); // 'hsl(258.3 89.5% 66.3%)'
resolveThemeColors({}, 'light'); // every token of a mode
```

`map` is the single intermediate representation: its `light` / `dark` maps hold one `palette.level` reference per token, and `Object.keys(map.light)` is the contract's token count.

With **[UnoCSS](/overview/installation)**, `presetUi()` (or `presetSbean()` when the theme lives in `sbean.json`) ships the palette layer and the default alias block as its preflight, so the tokens resolve with no runtime JavaScript; `@soybeanjs/ui/styles.css` is the equivalent prebuilt stylesheet. The adapter maps every token to a utility (`bg-card`, `text-card-foreground`, `border-input`, `bg-chart-1`), the palettes to `bg-indigo-500`-style rungs, and the roles to `bg-primary-500` / `text-destructive-100` style ramps.

### Colors

The theme system uses tailwindcss color presets.

## Component-level Style Customization

In addition to global theme configuration, you can fine-tune individual component styles using the `ui` prop.

### Using the ui prop

Multi-slot components support overriding each slot's style classes via the `ui` prop:

```vue
<script setup lang="ts">
import { SAccordion } from '@soybeanjs/ui';

const items = [
  { title: 'Title 1', value: 'item-1', description: 'Content 1' },
  { title: 'Title 2', value: 'item-2', description: 'Content 2' }
];
</script>

<template>
  <SAccordion
    :items="items"
    :ui="{
      root: 'border-2 border-primary',
      item: 'bg-card hover:bg-accent',
      trigger: 'text-lg font-bold',
      content: 'text-sm text-muted-foreground'
    }"
  />
</template>
```

### class prop merging

All components support the `class` prop, which intelligently merges with default styles:

```vue
<template>
  <SButton class="w-full rounded-full">Custom Button</SButton>
</template>
```

## Playground

- Page URL: /playground
- Markdown URL: /playground.md
- Description: Run the component examples in the browser and switch between the UI and Chart libraries.

# Playground

> Every shipped example, rendered live in the browser.

The playground lists the example SFCs bundled with the docs site and runs the selected one for real — no static snapshots.

## How it works

- **Library** — the select in the card header switches between `Headless`, `UI`, `Admin` and `Chart`. Examples currently exist for `UI` and `Chart`; the remaining libraries show an empty state until their examples land.
- **Tabs** — one tab per example folder (`apps/docs/src/examples/<library>/<component>/index.vue`).
- **Viewport** — every preview carries a screen-resolution switcher. `Desktop` is the fluid default; `Mobile` and `Tablet` pin the frame to a device width (390 px / 768 px) so responsive behaviour can be inspected without resizing the browser; `Fullscreen` lifts the preview into a viewport-filling layer, left with `Esc` or the exit button. Each example keeps its own resolution, and the frame publishes it through `provideViewportContext`, so components that resolve a mobile mode themselves (`SLayout`, `SAppShell`) switch with the switcher instead of the browser window.
- **Deep links** — the active tab is mirrored to the `?tab=` query parameter, so a specific example can be shared by URL.

## Where examples come from

Examples are plain SFCs under `apps/docs/src/examples/`. The same files back the `## Demos` section of every component page, so a change in the playground is a change in the documentation.