# Velkin UI — full component reference

> Index: https://velkinui.com/llms.txt · Consumer contract: https://velkinui.com/AGENTS.md · MCP: https://mcp.velkinui.com/mcp

Import from subpaths only (`@velkin/react/button`). React events are `onVu*` with payload in `e.detail`.
Capsule shape is `radius="full"` (no `pill`). Pro components need `@velkin/react-pro` + license.

# Inputs

# Advanced Filter

An advanced filter component with expression input and visual builder.

- **Tag:** `vu-advanced-filter`
- **Slug:** `advanced-filter`
- **Category:** Inputs
- **Tier:** Pro
- **React:** `VuAdvancedFilter` from `@velkin/react-pro/advanced-filter`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuAdvancedFilter } from "@velkin/react-pro/advanced-filter";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `VuAdvancedFilterColumn[]` | `[]` | Columns referenceable in expressions. Default: `[]`. |
| `query` | `string` | `""` | Controlled expression text. Default: `""`. |
| `label` | `string` | `""` | Accessible name override for the expression input. Default: `""`. |
| `placeholder` | `string` | `""` | Placeholder override for the expression input. Default: `""`. |
| `valueProvider` | `VuAdvancedFilterValueProvider \| null` | `null` | Supplies value suggestions per column key. Default: `null`. |
| `open` | `boolean` | `false` | Whether the visual builder popover is open. Default: `false`. |
| `disabled` | `boolean` | `false` | Disables the field, suggestions, and builder. Default: `false`. |
| `size` | `VuAdvancedFilterSize` | `"md"` | Density scale for overlays and inner controls. Default: `"md"`. |
| `tone` | `VuAdvancedFilterTone` | `"normal"` | Neutral surface weight for the field and overlays. Default: `"normal"`. |
| `placement` | `VuAdvancedFilterPlacement` | `"bottom"` | Preferred builder placement before flip. Default: `"bottom"`. |
| `align` | `VuAdvancedFilterAlign` | `"end"` | Builder alignment along the field edge. Default: `"end"`. |
| `offset` | `number` | `6` | Gap in px between the field and the builder popover. Default: `6`. |
| `width` | `string` | `""` | Builder panel inline size; empty uses stylesheet default. Default: `""`. |
| `maxHeight` | `string` | `""` | Max block size of the suggestions list; empty uses default. Default: `""`. |
| `radius` | `string` | `""` | Corner radius for the field, suggestions, and builder; empty uses token defaults. Default: `""`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuAdvancedFilterChangeDetail` | When the expression text changes. |
| `—` | `` | {CustomEvent<{ open: boolean }>} vu-open-change - When `open` changes (v-model). |
| `vu-open` | `void` | When the builder begins opening. |
| `vu-close` | `void` | When the builder begins closing. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Opens the visual builder popover. |
| `hide` | - Closes the visual builder popover. |
| `toggle` | - Toggles the visual builder popover. |
| `focus` | - Focuses the expression input. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Input field wrapper. |
| `input` | Native expression input. |
| `clear` | Clear-expression button. |
| `builder-trigger` | Visual builder toggle button. |
| `suggestions` | Type-ahead suggestions list. |
| `builder` | Visual builder popover surface. |
| `builder-dialog` | Expanded builder dialog surface. |

## Types

### `VuAdvancedFilterAlign`

```ts
"start" | "center" | "end"
```

### `VuAdvancedFilterChangeDetail`

```ts
{ query: string; }
```

### `VuAdvancedFilterPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuAdvancedFilterSize`

```ts
"sm" | "md" | "lg"
```

### `VuAdvancedFilterTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuAdvancedFilterValueProvider | null`

```ts
null | (field: string) => string[]
```

## Links

- Docs: https://velkinui.com/component/advanced-filter
- Markdown: https://velkinui.com/component/advanced-filter.md

---

# Button

A clickable button component with multiple variants and states.

- **Tag:** `vu-button`
- **Slug:** `button`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuButton` from `@velkin/react/button`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuButton } from "@velkin/react/button";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuButtonVariant` | `"solid"` | Visual treatment. Default: `"solid"`. |
| `color` | `VuButtonColor` | `"default"` | Token intent. Default: `"default"`. |
| `size` | `VuButtonSize` | `"md"` | Discrete size. Default: `"md"`. |
| `radius` | `VuButtonRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `"md"`. |
| `type` | `VuButtonType` | `"button"` | Native button type. Default: `"button"`. |
| `name` | `string` | `""` | Form-control name submitted with `type="submit"`. |
| `value` | `string` | `""` | Form-control value submitted with `name`. |
| `form` | `string` | `""` | ID of an external `<form>` to submit or reset. |
| `disabled` | `boolean` | `false` | Non-interactive; drops out of tab order. Default: `false`. |
| `loading` | `boolean` | `false` | Shows a spinner and blocks clicks. Default: `false`. |
| `block` | `boolean` | `false` | Stretches the button to fill its container. Default: `false`. |
| `iconOnly` | `boolean` | `false` | Square 1:1 hit target; `label` is `aria-label` only. Default: `false`. |
| `label` | `string` | `""` | Plain-text fallback for the default slot; icon-only buttons use it as `aria-label`. |
| `pressed` | `boolean` | `false` | Toggle or selected state; exposes `aria-pressed`. Default: `false`. |
| `preset` | `string` | — | Named bag from nearest `vu-config-provider`; omitted from the DOM while empty. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `click` | `MouseEvent` | Bubbles natively from the inner `<button>`. Suppressed when `disabled` or `loading`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Button label (text or markup). |
| `start` | Optional leading icon, rendered before the label. |
| `end` | Optional trailing icon, rendered after the label. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | The native `<button>` element (most styling lives here). |
| `start` | Wrapper around the leading icon slot. |
| `end` | Wrapper around the trailing icon slot. |
| `label` | Wrapper around the default text slot. |
| `spinner` | The loading spinner shown when `loading` is true. |

## Types

### `VuButtonColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuButtonRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuButtonSize`

```ts
"sm" | "md" | "lg"
```

### `VuButtonType`

```ts
"button" | "submit" | "reset"
```

### `VuButtonVariant`

```ts
"solid" | "outline" | "soft" | "ghost" | "link"
```

## Links

- Docs: https://velkinui.com/component/button
- Markdown: https://velkinui.com/component/button.md

---

# Button Group

A button group component with shared styling and optional selection.

- **Tag:** `vu-button-group`
- **Slug:** `button-group`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuButtonGroup` from `@velkin/react/button-group`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuButtonGroup } from "@velkin/react/button-group";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuButtonGroupVariant` | `"solid"` | Visual treatment forwarded to children. Default: `"solid"`. |
| `color` | `VuButtonGroupColor` | `"default"` | Token intent forwarded to children. Default: `"default"`. |
| `size` | `VuButtonGroupSize` | `"md"` | Discrete size forwarded to children. Default: `"md"`. |
| `radius` | `VuButtonGroupRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `orientation` | `VuButtonGroupOrientation` | `"horizontal"` | Layout axis. Default: `"horizontal"`. |
| `disabled` | `boolean` | `false` | Disables every child while set. Default: `false`. |
| `label` | `string` | `""` | Accessible name for the group container. |
| `selectionMode` | `VuButtonGroupSelectionMode` | `"none"` | Selection model; HTML attribute is `selectionmode`. Default: `"none"`. |
| `value` | `string` | `""` | Selected value when `selectionMode === "single"`. |
| `values` | `string[]` | `[]` | Selected values when `selectionMode === "multiple"`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuButtonGroupChangeDetail` | User toggled selection (not programmatic `value` / `values` writes). |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Two or more cluster members. Supported: `<vu-button>` and `<vu-dropdown>` (the dropdown's `[slot="trigger"]` `<vu-button>` is the visual surface that gets the cluster's variant / color / size / radius forwarded to it). Other tags are ignored — wrap raw `<button>` / `<a>` in `<vu-button>` first. `<vu-dropdown>` members are skipped from selection (`value` / `values`) — they remain trigger-only. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | The inner `[role="group"]` (or `[role="radiogroup"]`) container that wraps the slot. |

## Types

### `VuButtonGroupChangeDetail`

```ts
{ value: string; values: string[]; source: HTMLElement | null; }
```

### `VuButtonGroupColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuButtonGroupOrientation`

```ts
"horizontal" | "vertical"
```

### `VuButtonGroupRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuButtonGroupSelectionMode`

```ts
"none" | "single" | "multiple"
```

### `VuButtonGroupSize`

```ts
"sm" | "md" | "lg"
```

### `VuButtonGroupVariant`

```ts
"solid" | "outline" | "soft" | "ghost"
```

## Links

- Docs: https://velkinui.com/component/button-group
- Markdown: https://velkinui.com/component/button-group.md

---

# Checkbox

A checkbox component with label, hint, and validation.

- **Tag:** `vu-checkbox`
- **Slug:** `checkbox`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuCheckbox` from `@velkin/react/checkbox`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCheckbox } from "@velkin/react/checkbox";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Value restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks toggle (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change checked state (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when unchecked (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id forwarded to the internal input. |
| `value` | `string` | `""` | Form submit token when checked (`value` attr). |
| `color` | `VuCheckboxColor` | `"primary"` | Intent palette token for the checked accent. Default: `"primary"`. |
| `tone` | `VuCheckboxTone` | `"normal"` | Neutral idle-box weight (`subtle`/`normal`/`strong`). Default: `"normal"`. |
| `size` | `VuCheckboxSize` | `"md"` | Box, gap, and label scale (`sm`/`md`/`lg`). Default: `"md"`. |
| `radius` | `VuCheckboxRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. Uses `--vu-radius-*` (not control-radius) so the small box stays square-ish. |
| `variant` | `VuCheckboxVariant` | `"default"` | Box paint recipe. Default: `"default"`. |
| `indeterminateclick` | `VuCheckboxIndeterminateClick` | — | First click from indeterminate (`indeterminateclick` attr). Default: `"check"`. |
| `arialabel` | `string` | — | Accessible name when no visible label. |
| `compact` | `boolean` | `false` | Tighter hint/error spacing (`compact` attr). Default: `false`. |
| `defaultchecked` | `boolean` | — | Restored by `reset()` / form reset (`defaultchecked` attr). Default: `false`. |
| `showerrors` | `boolean` | — | Shows validation after first blur when `required` (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `checked` | `boolean` | — | Checked state (`checked` attr). Default: `false`. |
| `indeterminate` | `boolean` | — | Mixed/indeterminate state (`indeterminate` attr). Default: `false`. |
| `indeterminateClick` | `VuCheckboxIndeterminateClick` | `"check"` | First click from `indeterminate`: `check` (native) or `uncheck`. |
| `ariaLabel` | `string` | `""` | Inner input accessible name when no string or slotted label (icon-only). |
| `defaultChecked` | `boolean` | `false` | Target checked state for `reset()` and `<form>.reset()`; reflects as `defaultchecked`. |
| `showErrors` | `boolean` | `false` | When true with `required`, shows `requiredMessage` after first blur if unchecked; reflects as `showerrors`. |
| `validationActive` | `boolean` | `false` | After first blur with `showerrors`, drives invalid styling and error text. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuCheckboxChangeDetail` | User toggle; `detail.checked` boolean; `detail.value` submit token or boolean. |
| `vu-invalid` | `VuCheckboxValidationErrorDetail` | When validation messages are recomputed while `validationActive`. |
| `vu-clear` | `VuCheckboxValueClearedDetail` | After `reset()` syncs state from `defaultChecked`. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column that stacks the control row, optional hint, and optional error. |
| `wrapper` | The wrapper element for the checkbox. |
| `input` | The native input element used for the checkbox. |
| `label` | The label element for the checkbox, used for styling. |
| `box` | The visual box for the checkbox, which includes the checkmark and indeterminate state. |
| `checkmark` | The checkmark icon that appears when the checkbox is checked. |
| `indeterminate-line` | The line representing the indeterminate state of the checkbox. |
| `hint` | Neutral helper text under the label (string `hint` or `hint` slot). |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `text` | String `label` text when the `label` slot is empty. |

## Types

### `VuCheckboxChangeDetail`

```ts
{ checked: boolean; value: string | boolean | undefined; }
```

### `VuCheckboxColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuCheckboxIndeterminateClick`

```ts
"check" | "uncheck"
```

### `VuCheckboxRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuCheckboxSize`

```ts
"sm" | "md" | "lg"
```

### `VuCheckboxTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuCheckboxValidationErrorDetail`

```ts
{ errors: string[]; }
```

### `VuCheckboxValueClearedDetail`

```ts
{ value: string; checked: boolean; }
```

### `VuCheckboxVariant`

```ts
"outline" | "default" | "soft"
```

## Links

- Docs: https://velkinui.com/component/checkbox
- Markdown: https://velkinui.com/component/checkbox.md

---

# Checkbox Group

A checkbox group component with shared label and validation.

- **Tag:** `vu-checkbox-group`
- **Slug:** `checkbox-group`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuCheckboxGroup` from `@velkin/react/checkbox-group`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCheckboxGroup } from "@velkin/react/checkbox-group";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `VuCheckboxGroupOrientation` | `"vertical"` | `vertical` (default) stacks members; `horizontal` wraps them in a row. |
| `legend` | `string` | `""` | Plain-text in-group caption (muted vs string label); use slot="legend" for markup. |
| `label` | `string` | `""` | Plain-text field label above the group; use slot="label" for markup. |
| `hint` | `string` | `""` | Plain-text helper under the group; use `slot="hint"` for markup. |
| `ariaLabel` | `string` | `""` | Accessible name when there is no visible label or legend. |
| `variant` | `VuCheckboxVariant` | `"default"` | Forwarded to members that omit their own `variant`. |
| `color` | `VuCheckboxColor` | `"primary"` | Forwarded to members that omit their own `color`. |
| `tone` | `VuCheckboxTone` | `"normal"` | Forwarded to members that omit their own `tone`. |
| `size` | `VuCheckboxSize` | `"md"` | Forwarded to members that omit their own `size`. |
| `radius` | `VuCheckboxGroupRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `name` | `string` | — | Form field name forwarded to every member. Default: `""`. |
| `defaultvalue` | `string` | — | JSON array restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string \| null` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | `false` | Disables every member while set (releases only attrs this group claimed). |
| `readonly` | `boolean` | `false` | Forwarded to members; blocks interaction (inherited from `FormControlBase`). |
| `required` | `boolean` | `false` | When true, `checkValidity` / `reportValidity` fail until at least one member is checked. |
| `requiredMessage` | `string` | `"This field is required."` | Message for host `valueMissing` when `required` and nothing is selected. |
| `compact` | `boolean` | `false` | Tighter hint and error spacing. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `values` | `string[] \| undefined` | `undefined` | Selected member `value` tokens (`on` for empty member `value`); when set from JS, syncs member `checked`. Omit for uncontrolled usage. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuCheckboxGroupChangeDetail` | After a member toggles; `detail.values` mirrors `values` when controlled. Fired on the group host (not the member). |
| `vu-invalid` | `VuCheckboxGroupValidationErrorDetail` | When validation messages are recomputed while `validationActive`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - One or more `<vu-checkbox>` members (other nodes are ignored for forwarding). |
| `label` | Rich field label; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |
| `legend` | Rich legend inside the group; takes precedence over string `legend` when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column that stacks label, group, hint, and error. |
| `label` | Field label wrapper (string `label` or `label` slot). |
| `text` | String `label` when the `label` slot is empty. |
| `base` | `role="group"` wrapper (legend + default slot). |
| `legend` | In-group caption row; styled quieter than part label. |
| `fields` | Flex container around checkboxes. |
| `hint` | Helper text region (string `hint` or `hint` slot). |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |

## Types

### `string[] | undefined`

```ts
undefined | string[]
```

### `VuCheckboxColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuCheckboxGroupChangeDetail`

```ts
{ values: string[]; source: HTMLElement | null; }
```

### `VuCheckboxGroupOrientation`

```ts
"horizontal" | "vertical"
```

### `VuCheckboxGroupRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuCheckboxGroupValidationErrorDetail`

```ts
{ errors: string[]; }
```

### `VuCheckboxSize`

```ts
"sm" | "md" | "lg"
```

### `VuCheckboxTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuCheckboxVariant`

```ts
"outline" | "default" | "soft"
```

## Links

- Docs: https://velkinui.com/component/checkbox-group
- Markdown: https://velkinui.com/component/checkbox-group.md

---

# Color Area

A two-dimensional color picker component for saturation and brightness.

- **Tag:** `vu-color-area`
- **Slug:** `color-area`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuColorArea` from `@velkin/react/color-area`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuColorArea } from "@velkin/react/color-area";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |
| `invalid` | `boolean` | `false` | True when the last validation run found errors. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-input` | `VuColorAreaChangeDetail` | Continuous while dragging or adjusting with keys. |
| `vu-change` | `VuColorAreaChangeDetail` | Commit when the pointer releases or a discrete key moves. |
| `vu-invalid` | `CustomEvent` | When validation messages are recomputed while `validationActive`. |

## Slots

| Name | Description |
| --- | --- |
| `error` | Replaces default validation message list when assigned. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Clickable plane (CSS gradients or canvas). |
| `thumb` | Picked-color thumb. |
| `dots` | Optional `showdots` overlay. |
| `live` | Live region on commit. |
| `field` | Column that stacks the plane and optional error. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |

## Types

### `VuColorAreaChangeDetail`

```ts
{ colorSpace: VuColorAreaColorSpace; xChannel: VuColorAreaChannel; yChannel: VuColorAreaChannel; value: string; hue: number; saturation: number; brightness: number; red: number; green: number; blue: number; hsv: HSV; hsl: HSL; rgb: RGB; hex: string; css: string; }
```

## Links

- Docs: https://velkinui.com/component/color-area
- Markdown: https://velkinui.com/component/color-area.md

---

# Color Picker

A color picker component with swatches, sliders, and input field.

- **Tag:** `vu-color-picker`
- **Slug:** `color-picker`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuColorPicker` from `@velkin/react/color-picker`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuColorPicker } from "@velkin/react/color-picker";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | `"#3b82f6"` | Selected color as hex, rgb(), hsl(), or a named CSS color. Default: `"#3b82f6"`. |
| `format` | `VuColorPickerFormat` | `"hex"` | Text field and emitted string format. Default: `"hex"`. |
| `showalpha` | `boolean` | — | Renders the alpha slider (`showalpha` attr). Default: `false`. |
| `showformat` | `boolean` | — | Renders the hex / rgb / hsl format `<select>` (`showformat` attr). Default: `true`. |
| `swatches` | `string[]` | `[]` | Optional preset palette of CSS color strings. |
| `label` | `string` | `""` | Accessible name forwarded to area, sliders, and input. |
| `formatlabel` | `string` | — | Accessible name for the format `<select>` (`formatlabel` prop). |
| `swatcheslabel` | `string` | — | Accessible name for the preset swatch list (`swatcheslabel` prop). |
| `trigger` | `VuColorPickerTrigger` | `"inline"` | `inline` panel or `swatch` popover opener. Default: `"inline"`. |
| `placement` | `VuColorPickerPlacement` | `"bottom-start"` | Popover placement when `trigger="swatch"`. Default: `"bottom-start"`. |
| `open` | `boolean` | `false` | Popover open state when `trigger="swatch"`. Default: `false`. |
| `planecolorspace` | `VuColorAreaColorSpace` | — | 2D pad color model (`planecolorspace` attr). Default: `"hsb"`. |
| `planexchannel` | `VuColorAreaChannel` | — | Horizontal pad axis (`planexchannel` attr). Default: `"saturation"`. |
| `planeychannel` | `VuColorAreaChannel` | — | Vertical pad axis (`planeychannel` attr). Default: `"brightness"`. |
| `planeshowdots` | `boolean` | — | Passes `showdots` to `<vu-color-area>` (`planeshowdots` attr). Default: `false`. |
| `showarea` | `boolean` | — | Renders the 2D color pad (`showarea` attr). Default: `true`. |
| `showhueslider` | `boolean` | — | Renders the hue gradient slider (`showhueslider` attr). Default: `true`. |
| `showinput` | `boolean` | — | Renders the text color field (`showinput` attr). Default: `true`. |
| `showpreview` | `boolean` | — | Renders the live preview chip (`showpreview` attr). Default: `true`. |
| `sliderorientation` | `VuColorSliderOrientation` | — | Hue and alpha slider axis (`sliderorientation` attr). Default: `"horizontal"`. |
| `name` | `string` | — | Form field name for submit. |
| `defaultvalue` | `string` | — | Value restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks popover and input. |
| `readonly` | `boolean` | — | Focusable but value cannot be edited. |
| `required` | `boolean` | — | Blocks valid submit when empty. |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `showAlpha` | `boolean` | `false` | Renders the alpha slider (`showalpha` attr). |
| `showFormat` | `boolean` | `true` | Renders the format `<select>` (`showformat` attr). |
| `formatLabel` | `string` | `""` | Accessible name for the format `<select>`. |
| `swatchesLabel` | `string` | `""` | Accessible name for the preset swatch list. |
| `planeColorSpace` | `VuColorAreaColorSpace` | `"hsb"` | 2D pad color model (`planecolorspace` attr). |
| `planeXChannel` | `VuColorAreaChannel` | `"saturation"` | Horizontal pad axis (`planexchannel` attr). |
| `planeYChannel` | `VuColorAreaChannel` | `"brightness"` | Vertical pad axis (`planeychannel` attr). |
| `planeShowDots` | `boolean` | `false` | Passes `showdots` to `<vu-color-area>` (`planeshowdots` attr). |
| `showArea` | `boolean` | `true` | Renders the 2D color pad (`showarea` attr). |
| `showHueSlider` | `boolean` | `true` | Renders the hue slider (`showhueslider` attr). |
| `showInput` | `boolean` | `true` | Renders the text color field (`showinput` attr). |
| `showPreview` | `boolean` | `true` | Renders the live preview chip (`showpreview` attr). |
| `sliderOrientation` | `VuColorSliderOrientation` | `"horizontal"` | Hue and alpha slider axis (`sliderorientation` attr). |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-input` | `VuColorPickerChangeDetail` | Live value while dragging or typing. |
| `vu-change` | `VuColorPickerChangeDetail` | Committed value on pointer up, blur, or swatch pick. |
| `—` | `` | {CustomEvent<{ open: boolean }>} vu-open-change - When `open` changes (`trigger="swatch"`). |
| `vu-open` | `CustomEvent` | Popover opened (`trigger="swatch"`). |
| `vu-close` | `CustomEvent` | Popover closed (`trigger="swatch"`). |
| `vu-invalid` | `CustomEvent` | When validation messages are recomputed while `validationActive`. |

## Slots

| Name | Description |
| --- | --- |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Opens the swatch popover; no-op when `trigger="inline"`. |
| `hide` | - Closes the swatch popover; no-op when `trigger="inline"`. |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Picker body wrapper (area, sliders, input, swatches). |
| `sliders` | Hue and optional alpha slider group. |
| `row` | Preview chip, text input, and format toggle row. |
| `preview` | Live color preview chip. |
| `input` | Text input that round-trips the value. |
| `format` | Hex / rgb / hsl format `<select>`. |
| `swatches` | Preset swatch list container. |
| `trigger` | Swatch button when `trigger="swatch"`. |
| `popover` | Popover panel when `trigger="swatch"`. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `field` | Column that stacks the picker and optional error. |

## Types

### `VuColorAreaChannel`

```ts
"hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue"
```

### `VuColorAreaColorSpace`

```ts
"hsb" | "hsl" | "rgb"
```

### `VuColorPickerChangeDetail`

```ts
{ value: string; hex: string; hsv: HSV; hsl: HSL; rgb: RGB; alpha: number; }
```

### `VuColorPickerFormat`

```ts
"hsl" | "rgb" | "hex"
```

### `VuColorPickerPlacement`

```ts
"bottom-start" | "bottom-end" | "top-start" | "top-end"
```

### `VuColorPickerTrigger`

```ts
"inline" | "swatch"
```

### `VuColorSliderOrientation`

```ts
"horizontal" | "vertical"
```

## Links

- Docs: https://velkinui.com/component/color-picker
- Markdown: https://velkinui.com/component/color-picker.md

---

# Color Slider

A color slider component for adjusting individual color channels.

- **Tag:** `vu-color-slider`
- **Slug:** `color-slider`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuColorSlider` from `@velkin/react/color-slider`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuColorSlider } from "@velkin/react/color-slider";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `channel` | `VuColorSliderChannel` | `"hue"` | Which channel this slider edits. |
| `value` | `string` | `"#808080"` | Current color as a CSS string (two-way bindable). |
| `colorSpace` | `VuColorSliderColorSpace \| ""` | `""` | Color model when not inferable from `value` / `channel`. Leave blank to auto-resolve. |
| `orientation` | `VuColorSliderOrientation` | `"horizontal"` | Layout axis. |
| `step` | `number` | `NaN` | Keyboard step in the channel's native units. NaN uses channel defaults. |
| `baseColor` | `string` | `""` | Opaque color the alpha track fades up to; when blank, derived from the RGB of `value`. |
| `label` | `string` | `""` | Accessible name. Defaults to a channel-appropriate label. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |
| `invalid` | `boolean` | `false` | True when the last validation run found errors. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-input` | `VuColorSliderChangeDetail` | Continuous: every drag tick / key press. |
| `vu-change` | `VuColorSliderChangeDetail` | Commit: pointer release or discrete key move. |
| `vu-invalid` | `CustomEvent` | When validation messages are recomputed while `validationActive`.

Accessibility: host carries `role="slider"`, `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`, and `aria-orientation`. Keyboard: Arrow keys move by `step` (Shift × 10), Page keys jump by 10×, Home / End jump to extremes. The thumb is decorative; the host is the focus target.

Forms: form-associated via `FormControlBase`. Set `name` to participate in `<form>` submissions — the value is the CSS color string. `defaultvalue` controls `<form>.reset()`. Inherits `disabled`, `required`, and the standard validity surface. |

## Slots

| Name | Description |
| --- | --- |
| `error` | Replaces default validation message list when assigned. |

## CSS parts

| Name | Description |
| --- | --- |
| `track` | The clickable gradient strip for the active channel. |
| `thumb` | The position indicator. |
| `live` | Visually-hidden live region announcing the value on commit. |
| `field` | Column that stacks the track and optional error. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |

## Types

### `VuColorSliderChangeDetail`

```ts
{ value: string; color: VuColorSliderColor; channel: VuColorSliderChannel; channelValue: number; }
```

### `VuColorSliderChannel`

```ts
"hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha"
```

### `VuColorSliderColorSpace | ""`

```ts
"" | "hsb" | "hsl" | "rgb"
```

### `VuColorSliderOrientation`

```ts
"horizontal" | "vertical"
```

## Links

- Docs: https://velkinui.com/component/color-slider
- Markdown: https://velkinui.com/component/color-slider.md

---

# Color Swatch

A color swatch component for palettes, presets, and recent colors.

- **Tag:** `vu-color-swatch`
- **Slug:** `color-swatch`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuColorSwatch` from `@velkin/react/color-swatch`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuColorSwatch } from "@velkin/react/color-swatch";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `string` | `"transparent"` | CSS color painted on the chip. Default: `"transparent"`. |
| `value` | `string` | `""` | Selection token in `vu-select` detail; defaults to `color`. |
| `size` | `VuColorSwatchSize` | `"md"` | Visual size preset. Default: `"md"`. |
| `shape` | `VuColorSwatchShape` | `"circle"` | Chip outline (`circle` or `square`). Default: `"circle"`. |
| `checkerboard` | `boolean` | `false` | Transparency checkerboard under the fill (`checkerboard` attr). |
| `selected` | `boolean` | `false` | Contrast ring and checkmark (`selected` attr). Default: `false`. |
| `selectable` | `boolean` | `false` | Focusable and clickable; emits `vu-select` (`selectable` attr). |
| `disabled` | `boolean` | `false` | Disables interaction when `selectable` (`disabled` attr). |
| `readonly` | `boolean` | `false` | Focusable but does not emit `vu-select` when `selectable`. |
| `colorName` | `string` | `""` | Accessible name; blank defaults to `Color {color}`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-select` | `VuColorSwatchSelectDetail` | A `selectable` swatch was activated. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | The colored chip (`<button>` when selectable, `<div>` otherwise). |

## Types

### `VuColorSwatchSelectDetail`

```ts
{ color: string; value: string; }
```

### `VuColorSwatchShape`

```ts
"circle" | "square"
```

### `VuColorSwatchSize`

```ts
"sm" | "md" | "lg" | "xs" | "xl"
```

## Links

- Docs: https://velkinui.com/component/color-swatch
- Markdown: https://velkinui.com/component/color-swatch.md

---

# Color Swatch Picker

A color swatch picker component with preset or custom palettes.

- **Tag:** `vu-color-swatch-picker`
- **Slug:** `color-swatch-picker`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuColorSwatchPicker` from `@velkin/react/color-swatch-picker`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuColorSwatchPicker } from "@velkin/react/color-swatch-picker";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | `""` | Current selection (`swatch.value` or `swatch.color` when value is empty). |
| `colors` | `string[]` | `[]` | Auto-mode palette (CSS strings); ignored when slotted swatches exist. |
| `columns` | `number` | `0` | Grid column count; `0` = auto-fill (grid layout only). |
| `size` | `VuColorSwatchSize` | `"md"` | Swatch size forwarded to each chip. |
| `variant` | `VuColorSwatchPickerVariant` | `"circle"` | Swatch outline: `circle` (default) or `square`. |
| `layout` | `VuColorSwatchPickerLayout` | `"grid"` | `grid` (default) or vertical `stack`. |
| `label` | `string` | `""` | Accessible name for the radiogroup; empty uses the locale catalog. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |
| `invalid` | `boolean` | `false` | True when the last validation run found errors. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuColorSwatchPickerChangeDetail` | Selection changed. |
| `vu-invalid` | `CustomEvent` | When validation messages are recomputed while `validationActive`.

Forms: `name` + `value`; `defaultvalue` seeds `<form>.reset()`. Inherits `disabled`, `required`, validity. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Optional `<vu-color-swatch>` children (composition mode). When non-empty, `colors` is ignored. |
| `error` | Replaces default validation message list when assigned. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Swatch container (grid or stack). |
| `field` | Column that stacks the palette and optional error. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |

## Types

### `VuColorSwatchPickerChangeDetail`

```ts
{ value: string; color: string; index: number; parsed: VuColorSwatchPickerColor | null; }
```

### `VuColorSwatchPickerLayout`

```ts
"grid" | "stack"
```

### `VuColorSwatchPickerVariant`

```ts
"circle" | "square"
```

### `VuColorSwatchSize`

```ts
"sm" | "md" | "lg" | "xs" | "xl"
```

## Links

- Docs: https://velkinui.com/component/color-swatch-picker
- Markdown: https://velkinui.com/component/color-swatch-picker.md

---

# Combobox

A combobox component with search, single or multi select, and validation.

- **Tag:** `vu-combobox`
- **Slug:** `combobox`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuCombobox` from `@velkin/react/combobox`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCombobox } from "@velkin/react/combobox";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuComboboxVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuComboboxTone` | `"normal"` | Neutral chrome weight. Default: `"normal"`. |
| `size` | `VuComboboxSize` | `"md"` | Field scale. Default: `"md"`. |
| `radius` | `VuComboboxRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the trigger to the container width. Default: `false`. |
| `name` | `string` | — | Form field name. Default: `""`. |
| `defaultValue` | `string` | — | Uncontrolled initial value; HTML attribute is `value`. Default: `""`. |
| `formId` | `string \| null` | — | ID of an external `<form>`; HTML attribute is `formid`. Default: `null`. |
| `disabled` | `boolean` | `false` | Non-interactive state. Default: `false`. |
| `readonly` | `boolean` | `false` | Read-only; keeps focus without editing. Default: `false`. |
| `required` | `boolean` | `false` | Marks the field required for form validation. Default: `false`. |
| `requiredMessage` | `string` | `"Selection is required."` | Message when `required` fails. Default: `"Selection is required."`. |
| `value` | `VuComboboxValue` | `""` | Current selection; string or array when `multiple`. |
| `placeholder` | `string` | `"Select An Option"` | Empty-state hint and filter placeholder when `searchable`. |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `options` | `VuComboboxOption[]` | `[]` | Option list (`string` or `{ label, value }`). |
| `renderer` | `VuComboboxRendererFn \| null` | `null` | Per-row dropdown renderer; omit for default label. |
| `clearable` | `boolean` | `false` | Shows a clear control when a value is present. Default: `false`. |
| `loading` | `boolean` | `false` | Shows a loading row in the options panel. Default: `false`. |
| `searchable` | `boolean` | `false` | Filter-as-you-type in the field. Default: `false`. |
| `multiple` | `boolean` | `false` | Multi-select chips instead of a single value. Default: `false`. |
| `visibleChips` | `number` | `2` | Max chips shown inline before +N overflow. Default: `2`. |
| `showErrors` | `boolean` | `false` | Renders validation errors below the field. Default: `false`. |
| `addOption` | `boolean` | `false` | Allows creating a new option from the filter query. Default: `false`. |
| `id` | `string` | `""` | Host id; also prefixes internal control ids when set. |
| `ariaLabel` | `string` | `""` | Accessible name when no visible label is present. |
| `validationActive` | `boolean` | `false` | Shows validation affordances after first interaction. Default: `false`. |
| `invalid` | `boolean` | `false` | Reflects validation failure state. Default: `false`. |
| `query` | `string` | `""` | Current field filter for controlled filtering. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuComboboxChangeDetail` | Fired whenever selection changes. |
| `vu-input` | `VuComboboxInputDetail` | Fired when the field filter query changes. |
| `vu-invalid` | `VuComboboxInvalidDetail` | Fired when validation messages are recomputed. |
| `vu-add` | `VuComboboxAddDetail` | Fired when the user confirms adding a new option. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |
| `start` | Leading unit or symbol inside the field container. |
| `end` | Trailing unit or symbol inside the field container. |

## Methods

| Name | Description |
| --- | --- |
| `openDropdown` | Opens the options panel. |
| `closeDropdown` | Closes the options panel. |
| `clearSelection` | Clears current selection if allowed. |
| `reset` | Resets combobox state and clears validation UI. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, control row, hint, and error. |
| `label` | Label wired to the trigger. |
| `start` | Leading affix wrapper. |
| `end` | Trailing affix wrapper. |
| `container` | Interactive field trigger (chips, placeholder, actions). |
| `value` | Chip + filter input row when `searchable` or `addOption`. |
| `placeholder-label` | Placeholder when no value is selected. |
| `clear-button` | Clear selection control. |
| `dropdown-button` | Chevron toggle control. |
| `dropdown-loading` | Loading row in the options panel. |
| `dropdown-loading-indicator` | Spinner inside the dropdown loading row. |
| `dropdown-loading-label` | Loading copy in the dropdown panel. |
| `chip-container` | Multi-select chip row. |
| `chip` | Individual chip in multi-select mode. |
| `single-select-chip` | Single-select value label. |
| `overflow-chip` | +N overflow chip. |
| `remove-chip-icon` | Remove icon on chips. |
| `hidden-chips-dropdown` | Overflow chip popover panel. |
| `hidden-chip-inner` | Row inside the overflow panel. |
| `hidden-chip-label` | Label in overflow panel rows. |
| `dropdown` | Main options popover panel. |
| `input` | Field filter text input when `searchable` or `addOption`. |
| `add-option-icon` | Add-new-option affordance in the field. |
| `select-all` | Select-all row in multi-select mode. |
| `option` | One selectable option row. |
| `option-content` | Custom or default label region inside an option row. |
| `highlighted-text` | Search-highlighted label text. |
| `no-options` | Empty filter message row. |
| `dropdown-scroller` | Scrollable options region. |
| `hint` | Helper text region. |
| `error-message` | Validation error region. |
| `error-line` | One default validation string. |

## Types

### `VuComboboxAddDetail`

```ts
{ value: string; }
```

### `VuComboboxChangeDetail`

```ts
{ value: VuComboboxValue; selectedItems: VuComboboxOption[]; }
```

### `VuComboboxInputDetail`

```ts
{ query: string; }
```

### `VuComboboxInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuComboboxRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuComboboxRendererFn | null`

```ts
null | (context: VuComboboxRendererContext) => TemplateResult | string | null | undefined
```

### `VuComboboxSize`

```ts
"sm" | "md" | "lg"
```

### `VuComboboxTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuComboboxValue`

```ts
string | string[]
```

### `VuComboboxVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/combobox
- Markdown: https://velkinui.com/component/combobox.md

---

# Counter

A counter component for numeric input with label, hint, and validation.

- **Tag:** `vu-counter`
- **Slug:** `counter`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuCounter` from `@velkin/react/counter`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCounter } from "@velkin/react/counter";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Restored on `<form reset>`; falls back to `defaultnumber` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks stepping and typing (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change value (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when empty (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id forwarded to the internal input. |
| `value` | `number` | `0` | Current value; `NaN` when empty with `allowempty`. Default: `0`. |
| `variant` | `VuCounterVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuCounterTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuCounterSize` | `"md"` | Control scale. Default: `"md"`. |
| `radius` | `VuCounterRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the stepper to the container width. Default: `false`. |
| `compact` | `boolean` | `false` | Tighter label/hint/error spacing. Default: `false`. |
| `min` | `number` | `0` | Minimum allowed value. Default: `0`. |
| `max` | `number` | — | Optional maximum allowed value. |
| `step` | `number` | `1` | Increment/decrement step size. Default: `1`. |
| `allowtyping` | `boolean` | — | Enables direct typing in the number input. Default: `false`. |
| `allowempty` | `boolean` | — | Permits an empty field (`NaN`) until blur when typing. Default: `false`. |
| `wrap` | `boolean` | `false` | At bounds, step wraps to the opposite bound. Default: `false`. |
| `commitonly` | `boolean` | — | Typing emits `vu-change` on blur only; buttons emit immediately. Default: `false`. |
| `precision` | `number` | `0` | Decimal places applied on blur and programmatic sets. Default: `0`. |
| `placeholder` | `string` | `""` | Shown when the value is empty (`NaN`). |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `icondecrease` | `string` | — | Iconify id for the decrease button. |
| `iconincrease` | `string` | — | Iconify id for the increase button. |
| `defaultnumber` | `number` | — | Baseline for `reset()` when `defaultvalue` is unset. Default: `0`. |
| `decreaselabel` | `string` | — | Accessible name for the decrease button. |
| `increaselabel` | `string` | — | Accessible name for the increase button. |
| `arialabel` | `string` | — | Input name when no visible label is present. |
| `holddelay` | `number` | — | ms before press-and-hold repeat starts. Default: `400`. |
| `holdinterval` | `number` | — | ms between repeats while held. Default: `80`. |
| `holdaccelerate` | `boolean` | — | Halves repeat interval after sustained hold. Default: `true`. |
| `allowTyping` | `boolean` | `false` | Enables direct typing in the number input. |
| `allowEmpty` | `boolean` | `false` | Permits an empty field (`NaN`) until blur when typing. |
| `commitOnly` | `boolean` | `false` | Typing emits `vu-change` on blur only; buttons emit immediately. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `iconDecrease` | `"ion:remove"` | `"ion:remove"` | Iconify id for the decrease button. |
| `iconIncrease` | `"ion:add"` | `"ion:add"` | Iconify id for the increase button. |
| `defaultNumber` | `number` | `0` | Baseline for `reset()` when `defaultvalue` is unset. |
| `decreaseLabel` | `string` | `""` | Accessible name for the decrease button. |
| `increaseLabel` | `string` | `""` | Accessible name for the increase button. |
| `ariaLabel` | `string` | `""` | Input name when no visible label is present. |
| `holdDelay` | `number` | `400` | ms before press-and-hold repeat starts. |
| `holdInterval` | `number` | `80` | ms between repeats while held. |
| `holdAccelerate` | `boolean` | `true` | Halves repeat interval after sustained hold. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuCounterChangeDetail` | Value updates (`detail.previous`, `detail.reason`). |
| `vu-clear` | `VuCounterClearDetail` | After `reset()` syncs the default value. |
| `vu-invalid` | `VuCounterInvalidDetail` | When validation messages are recomputed. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |
| `start` | Leading unit or symbol inside the field container. |
| `end` | Trailing unit or symbol inside the field container. |

## Methods

| Name | Description |
| --- | --- |
| `increment` | - Increases value by `step`. |
| `decrement` | - Decreases value by `step`. |
| `setValue` | - Sets value after clamp/snap and emits `vu-change`. |
| `reset` | - Restores baseline value and dispatches `vu-clear`. |
| `validateInput` | - Recomputes validation messages and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, control row, hint, and error. |
| `label` | Label element wired to the input. |
| `start` | Leading affix wrapper. |
| `end` | Trailing affix wrapper. |
| `container` | Stepper chrome (buttons + input). |
| `button` | Shared part on decrease and increase buttons. |
| `button--decrease` | Decrease button. |
| `button--increase` | Increase button. |
| `icon` | Shared part on decrease and increase icons. |
| `icon--decrease` | Decrease icon. |
| `icon--increase` | Increase icon. |
| `input` | Numeric input field. |
| `hint` | Helper text region. |
| `error-message` | Validation error region. |
| `error-line` | One default validation string. |

## Types

### `VuCounterChangeDetail`

```ts
{ value: number; previous: number; reason: VuCounterChangeReason; }
```

### `VuCounterClearDetail`

```ts
{ value: number; }
```

### `VuCounterInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuCounterRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuCounterSize`

```ts
"sm" | "md" | "lg"
```

### `VuCounterTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuCounterVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/counter
- Markdown: https://velkinui.com/component/counter.md

---

# Date Picker

A date picker component with field input and optional calendar panel.

- **Tag:** `vu-date-picker`
- **Slug:** `date-picker`
- **Category:** Inputs
- **Tier:** Pro
- **React:** `VuDatePicker` from `@velkin/react-pro/date-picker`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuDatePicker } from "@velkin/react-pro/date-picker";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `VuDatePickerMode` | `"date"` | Selection mode (`date`, `range`, `time`, …). Default: `"date"`. |
| `variant` | `VuDatePickerVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuDatePickerTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuDatePickerSize` | `"md"` | Control scale and corner radius. Default: `"md"`. |
| `radius` | `VuDatePickerRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the field to the container width. Default: `false`. |
| `compact` | `boolean` | `false` | Tighter label, hint, and error spacing. Default: `false`. |
| `inline` | `boolean` | `false` | Renders the calendar panel inline (no popover). Default: `false`. |
| `open` | `boolean` | `false` | Popover panel open state. Default: `false`. |
| `closeonselect` | `boolean` | `true` | Closes the panel after a complete selection. Default: `true`. |
| `focusopen` | `boolean` | `false` | Opens the panel when the field receives focus. Default: `false`. |
| `color` | `string` | `"primary"` | Accent token for calendar and time chrome. Default: `"primary"`. |
| `value` | `string` | `""` | Committed date/time string. Default: `""`. |
| `format` | `string` | `""` | Display/wire pattern (`yyyy-MM-dd`, `dd/MM/yyyy HH:mm`, …). Default: `""`. |
| `valueformat` | `VuDatePickerValueFormat` | `"local"` | Preset when `format` is empty. Default: `"local"`. |
| `placeholder` | `string` | `""` | Input placeholder; derived from `format` when empty. |
| `label` | `string` | `""` | Plain-text label; `label` slot wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `firstdayofweek` | `number` | — | Week start day index (0 = Sunday). Default: `1`. |
| `calendars` | `number` | `1` | Side-by-side month grids in the panel (1–3). Default: `1`. |
| `mobilemode` | `VuDatePickerMobileMode` | `"auto"` | Mobile shell strategy. Default: `"auto"`. |
| `segmented` | `boolean` | `false` | Segmented format input (`mode="date"` only). Default: `false`. |
| `adapter` | `DateAdapter \| null` | `null` | Optional parse/format adapter; default engine when omitted. |
| `sundayholiday` | `boolean` | — | Styles Sundays as non-interactive holidays. Default: `false`. |
| `constraints` | `VuDatePickerConstraints` | `{}` | Min/max and disabled matchers. Default: `{}`. |
| `showerrors` | `boolean` | — | Shows validation messages after `validationActive`. Default: `false`. |
| `validationactive` | `boolean` | — | Activates hint and error display. Default: `false`. |
| `invalid` | `boolean` | `false` | Marks the field invalid for assistive tech. Default: `false`. |
| `arialabel` | `string` | — | Accessible name when no visible label (`arialabel` attr). |
| `name` | `string` | — | Form field name for submit. |
| `defaultvalue` | `string` | — | Value restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks panel and input. Default: `false`. |
| `readonly` | `boolean` | — | Focusable but value cannot be edited. Default: `false`. |
| `required` | `boolean` | — | Blocks valid submit when empty. Default: `false`. |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `firstDayOfWeek` | `number` | `1` | Week start day index (0 = Sunday). |
| `sundayHoliday` | `boolean` | `false` | Styles Sundays as non-interactive holidays. |
| `showErrors` | `boolean` | `false` | Shows validation messages after `validationActive`. |
| `validationActive` | `boolean` | `false` | Activates hint and error display. |
| `ariaLabel` | `string` | `""` | Accessible name when no visible label is present. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuDatePickerChangeDetail` | When the committed value changes. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |
| `start` | Leading affix inside the field container. |
| `end` | Trailing affix inside the field container. |
| `actions` | Footer actions inside the calendar panel. |
| `extra` | Content below the calendar inside the panel. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Opens the popover panel. |
| `hide` | - Closes the popover panel. |
| `toggle` | - Toggles the popover panel. |
| `reset` | - Clears the value and draft selection. |

## CSS parts

| Name | Description |
| --- | --- |
| `container` | Field chrome wrapping the input and trigger. |
| `start` | Leading affix wrapper. |
| `end` | Trailing affix wrapper. |
| `input` | Text input or embedded segmented field. |
| `trigger` | Calendar icon button opening the panel. |
| `panel` | Popover panel hosting the layout. |
| `sheet` | Mobile bottom-sheet surface inside the panel. |
| `sheet-header` | Mobile toolbar row (Cancel / title / OK). |
| `sheet-title` | Mobile sheet heading. |
| `sheet-action` | Mobile toolbar action button. |
| `sheet-body` | Scrollable calendar region in the mobile shell. |
| `inline-panel` | Inline layout region when `inline` is set. |

## Types

### `DateAdapter | null`

```ts
null | DateAdapter
```

### `VuDatePickerChangeDetail`

```ts
{ value: string; date?: string | null; range?: { start: string | null; end: string | null; }; time?: string | null; timeRange?: { from: string | null; to: string | null; }; rangeWithTime?: { start: string | null; end: string | null; }; dates?: string[]; week?: string | null; }
```

### `VuDatePickerConstraints`

```ts
{ [P in keyof T]?: T[P] | undefined; }
```

### `VuDatePickerMobileMode`

```ts
"auto" | "popover" | "dialog"
```

### `VuDatePickerMode`

```ts
"date" | "range" | "multi" | "week" | "datetime" | "time" | "datetime-range" | "time-range"
```

### `VuDatePickerRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuDatePickerSize`

```ts
"sm" | "md" | "lg"
```

### `VuDatePickerTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuDatePickerValueFormat`

```ts
"local" | "iso"
```

### `VuDatePickerVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/date-picker
- Markdown: https://velkinui.com/component/date-picker.md

---

# File Picker

A file picker component with drag-and-drop and validation.

- **Tag:** `vu-file-picker`
- **Slug:** `file-picker`
- **Category:** Inputs
- **Tier:** Pro
- **React:** `VuFilePicker` from `@velkin/react-pro/file-picker`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuFilePicker } from "@velkin/react-pro/file-picker";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `files` | `File[]` | `[]` | Selected files in multiple mode. Default: `[]`. |
| `file` | `File \| null` | `null` | Selected file in single mode. Default: `null`. |
| `multiple` | `boolean` | `false` | Enables multiple file selection. Default: `false`. |
| `accept` | `string` | `""` | Comma-separated accepted extensions or wildcards. Default: `""`. |
| `maxSize` | `number` | `15` | Maximum file size in MB. Default: `15`. |
| `errorMessage` | `string` | `""` | Current picker validation error (type/size). Default: `""`. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `showStructure` | `boolean` | `false` | Shows selected files inline. Default: `false`. |
| `showRemoveButtons` | `boolean` | `true` | Shows remove control on each listed file. Default: `true`. |
| `allowAllFiles` | `boolean` | `false` | Skips extension filtering. Default: `false`. |
| `droppable` | `boolean` | `false` | Enables drag-and-drop selection. Default: `false`. |
| `dragText` | `string` | `""` | Dropzone placeholder; empty uses locale catalog. Default: `""`. |
| `density` | `VuFilePickerDensity` | `"default"` | Dropzone layout density (arrangement; not field `size`). Default: `"default"`. |
| `icon` | `"ion:cloud-upload"` | `"ion:cloud-upload"` | Dropzone icon name. Default: cloud upload icon. |
| `buttonLabel` | `string` | `""` | Trigger button label; empty uses locale catalog. Default: `""`. |
| `directory` | `boolean` | `false` | Enables directory picking mode. Default: `false`. |
| `emitHandles` | `boolean` | `false` | Includes file system handles in event detail. Default: `false`. |
| `filepairId` | `string` | `""` | Pairing id for linked file viewer. Default: `""`. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |
| `dragging` | `boolean` | `false` | True while external files are dragged over the dropzone. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `CustomEvent` | When selected files change. |
| `vu-invalid` | `VuFilePickerInvalidDetail` | When validation fails or selection is cancelled. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Custom dropzone content. |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `validateInput` | - Runs validators and syncs validity. |
| `openFilePicker` | - Opens file or directory picker based on directory mode. |
| `clear` | - Clears current selection and emits `vu-change`. |
| `removeFileAt` | - Removes one selected file by index. |
| `removeFile` | - Removes one selected file by reference. |
| `dispatchError` | - Emits `vu-invalid` and updates error state. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column that stacks dropzone, optional file list, and error. |
| `dropzone` | Outer drop area container. |
| `drop-content` | Inner dropzone content wrapper. |
| `drop-icon` | Icon container inside the dropzone. |
| `drop-placeholder` | Empty-state placeholder text. |
| `file-picker-button` | Browse or select-folder trigger button. |
| `drop-overlay` | Full-surface overlay during drag-over. |
| `file-structure` | Wrapper for the optional file list. |
| `file-list` | List of selected file names. |
| `file-item` | One selected file row. |
| `file-name` | File name text in the structure list. |
| `file-remove` | Remove control for one listed file. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |

## Types

### `CustomEvent`

```ts
VuFilePickerSelectedSingleDetail | VuFilePickerSelectedMultiDetail
```

### `File | null`

```ts
null | File
```

### `VuFilePickerDensity`

```ts
"default" | "compact" | "comfortable"
```

### `VuFilePickerInvalidDetail`

```ts
{ error: string; }
```

## Links

- Docs: https://velkinui.com/component/file-picker
- Markdown: https://velkinui.com/component/file-picker.md

---

# Form

A form component for validation, FormData, and submit coordination.

- **Tag:** `vu-form`
- **Slug:** `form`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuForm` from `@velkin/react/form`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuForm } from "@velkin/react/form";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `liveValidation` | `boolean` | `false` | Validates and emits `vu-change` on value changes. Default: `false`. |
| `showErrors` | `boolean` | `true` | Activates error display on child fields after submit/invalid. Default: `true`. |
| `mode` | `VuFormMode` | `"client"` | Submission mode (`client` or `server`). Default: `"client"`. |
| `method` | `VuFormMethod` | — | Native form method in server mode. |
| `action` | `string` | — | Native form action in server mode. |
| `target` | `string` | — | Native form target in server mode. |
| `enctype` | `VuFormEnctype` | — | Native form encoding type. |
| `autocomplete` | `VuFormAutocomplete` | — | Native form autocomplete behavior. |
| `noValidate` | `boolean` | `false` | Disables native HTML constraint UI. Default: `false`. |
| `enterSubmit` | `boolean` | `false` | Submits on Enter for non-textarea controls. Default: `false`. |
| `resetOnSubmit` | `boolean` | `false` | Resets form after successful submit. Default: `false`. |
| `csrfToken` | `string \| null` | `null` | Optional CSRF token value for app-level submit handling. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuFormChangeDetail` | When form values change in live validation mode. |
| `vu-invalid` | `VuFormInvalidDetail` | When aggregated validation errors change. |
| `formdata` | `VuFormFormDataFallbackDetail` | Before client-mode submit with form data. |
| `vu-submit` | `VuFormSubmitDetail` | After successful client-mode submit handling. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Form controls and actions projected into the native `<form>`. |

## Methods

| Name | Description |
| --- | --- |
| `checkValidity` | - Returns native form validity without UI reporting. |
| `reportValidity` | - Returns native form validity and reports native UI messages. |
| `requestSubmit` | - Requests submission using optional submitter. |
| `reset` | - Resets native form and values. |
| `submit` | - Submits form using mode-specific client/server flow. |

## CSS parts

| Name | Description |
| --- | --- |
| `form` | Native `<form>` element.

Light DOM host: copies host `id` onto the inner `<form>` and assigns `form="<id>"` to associated controls outside the native form subtree. |

## Types

### `string | null`

```ts
null | string
```

### `VuFormAutocomplete`

```ts
"on" | "off"
```

### `VuFormChangeDetail`

```ts
{ values: VuFormValues; formData: FormData; success: boolean; }
```

### `VuFormEnctype`

```ts
"application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain"
```

### `VuFormFormDataFallbackDetail`

```ts
{ formData: FormData; }
```

### `VuFormInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuFormMethod`

```ts
"get" | "post"
```

### `VuFormMode`

```ts
"client" | "server"
```

### `VuFormSubmitDetail`

```ts
{ values: VuFormValues; formData: FormData; success: boolean; }
```

## Links

- Docs: https://velkinui.com/component/form
- Markdown: https://velkinui.com/component/form.md

---

# Input

A text field component with label, hint, and validation.

- **Tag:** `vu-input`
- **Slug:** `input`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuInput` from `@velkin/react/input`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuInput } from "@velkin/react/input";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuInputVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuInputTone` | `"normal"` | Neutral chrome weight. Default: `"normal"`. |
| `size` | `VuInputSize` | `"md"` | Field scale. Default: `"md"`. |
| `radius` | `VuInputRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the field to the container width. Default: `false`. |
| `name` | `string` | — | Form field name. Default: `""`. |
| `defaultValue` | `string` | — | Uncontrolled initial value; HTML attribute is `value`. Default: `""`. |
| `formId` | `string \| null` | — | ID of an external `<form>`; HTML attribute is `formid`. Default: `null`. |
| `disabled` | `boolean` | — | Non-interactive state. Default: `false`. |
| `readonly` | `boolean` | — | Read-only; keeps focus without editing. Default: `false`. |
| `required` | `boolean` | `false` | Marks the field required for form validation. Default: `false`. |
| `requiredMessage` | `string` | — | Message when `required` fails. Default: `"This field is required."`. |
| `value` | `VuInputValue` | `""` | Current value; `number` when `type="number"`. |
| `placeholder` | `string` | `""` | Placeholder or file-input fallback label. |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `type` | `VuInputType` | `"text"` | Native type, or `textarea` / `file`. Default: `"text"`. |
| `validations` | `VuInputValidation[]` | — | Custom validators returning `true` or an error string. |
| `compact` | `boolean` | `false` | Tighter vertical spacing. Default: `false`. |
| `loading` | `boolean` | `false` | Shows a trailing spinner. Default: `false`. |
| `showErrors` | `boolean` | `false` | Shows validation messages after `validationActive`. Default: `false`. |
| `clearable` | `boolean` | `false` | Shows a clear button when the field has a value. Default: `false`. |
| `showNumberButtons` | `boolean` | `false` | Shows +/- controls for `type="number"`. Default: `false`. |
| `showPasswordToggle` | `boolean` | `true` | Shows a password visibility toggle. Default: `true`. |
| `step` | `string \| null` | `null` | Native `step` for number inputs. |
| `min` | `string \| null` | `null` | Native `min` constraint. |
| `max` | `string \| null` | `null` | Native `max` constraint. |
| `autocapitalize` | `string` | `"off"` | Native `autocapitalize`. Default: `"off"`. |
| `autocomplete` | `string` | `"off"` | Native `autocomplete`. Default: `"off"`. |
| `spellcheck` | `boolean` | `false` | Native `spellcheck`. Default: `false`. |
| `dir` | `string` | `"ltr"` | Text direction. Default: `"ltr"`. |
| `rows` | `number` | `6` | Textarea row count. Default: `6`. |
| `resizable` | `string` | `"none"` | Textarea resize mode. Default: `"none"`. |
| `accept` | `string` | `""` | File input accept filter. |
| `multiple` | `boolean` | `false` | Allows multiple files when `type="file"`. Default: `false`. |
| `inputmode` | `string \| null` | `null` | Native `inputmode` hint. |
| `enterkeyhint` | `string \| null` | `null` | Native `enterkeyhint` for virtual keyboards. |
| `pattern` | `string \| null` | `null` | Native `pattern` validation regex. |
| `minlength` | `number \| null` | `null` | Native minimum string length. |
| `maxlength` | `number \| null` | `null` | Native maximum string length. |
| `list` | `string \| null` | `null` | ID of a `<datalist>` to associate. |
| `nativeSize` | `number \| null` | `null` | Native `size` attribute (character width). |
| `autofocus` | `boolean` | `false` | Focuses the control on connect. Default: `false`. |
| `capture` | `boolean` | `false` | Enables capture on file inputs. Default: `false`. |
| `ariaLabel` | `string` | `""` | Accessible name when no visible label is present. |
| `ariaLabelledby` | `string \| null` | `null` | IDs of elements that label the control. |
| `id` | `string` | `""` | Host id; also prefixes internal control ids when set. |
| `validationActive` | `boolean` | `false` | Shows validation affordances after interaction. Default: `false`. |
| `invalid` | `boolean` | `false` | Reflects validation failure state. Default: `false`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuInputChangeDetail` | When the value updates. |
| `vu-clear` | `VuInputClearDetail` | After the value is cleared. |
| `vu-invalid` | `VuInputInvalidDetail` | When validation messages are recomputed. |
| `vu-file` | `VuInputFileDetail` | After file selection changes. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |
| `start` | Leading icon or affix inside the field container. |
| `end` | Trailing icon or affix inside the field container. |

## Methods

| Name | Description |
| --- | --- |
| `validateInput` | - Recomputes validation messages and returns whether the field is valid. |
| `clear` | - Clears the value and emits `vu-clear`. |
| `focus` | - Focuses the native control. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, control row, hint, and error. |
| `label` | Label wired to the native control. |
| `start` | Leading affix wrapper. |
| `end` | Trailing affix wrapper. |
| `container` | Field chrome wrapping the native control and actions. |
| `input` | Native `<input>` or `<textarea>`. |
| `toggle-password` | Password visibility toggle. |
| `clear-button` | Clear value control. |
| `loading-indicator` | Loading spinner on the trailing edge. |
| `number-stepper` | Increment/decrement button group for `type="number"`. |
| `button` | Shared part on stepper buttons. |
| `button--decrease` | Decrease button. |
| `button--increase` | Increase button. |
| `hint` | Helper text region. |
| `error-message` | Validation error region. |
| `error-line` | One default validation string. |
| `file-info` | Selected file count and size readout. |
| `file-label` | Visible label for file inputs. |

## Types

### `number | null`

```ts
null | number
```

### `string | null`

```ts
null | string
```

### `VuInputChangeDetail`

```ts
{ value: string | number; previous: string | number; }
```

### `VuInputClearDetail`

```ts
{ value: string | number; }
```

### `VuInputFileDetail`

```ts
{ files: File[]; fileName: string; totalSize: number; fileCount: number; }
```

### `VuInputInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuInputRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuInputSize`

```ts
"sm" | "md" | "lg"
```

### `VuInputTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuInputType`

```ts
string
```

### `VuInputValue`

```ts
null | string | number
```

### `VuInputVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/input
- Markdown: https://velkinui.com/component/input.md

---

# Otp

An OTP input component with segmented fields, paste support, and validation.

- **Tag:** `vu-otp`
- **Slug:** `otp`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuOtp` from `@velkin/react/otp`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuOtp } from "@velkin/react/otp";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks cell entry (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change cells (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when incomplete (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id for label `for` / `aria-*` wiring. |
| `variant` | `VuOtpVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuOtpTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuOtpSize` | `"md"` | Cell scale. Default: `"md"`. |
| `radius` | `VuOtpRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the cell row to the container width. Default: `false`. |
| `compact` | `boolean` | `false` | Tighter label/hint/error spacing. Default: `false`. |
| `length` | `number` | `6` | Number of OTP characters. Default: `6`. |
| `alphanumeric` | `boolean` | `false` | Allows letters in addition to digits. Default: `false`. |
| `value` | `string` | `""` | Canonical OTP string (unmasked). Default: `""`. |
| `masked` | `boolean` | `false` | Masks cell glyphs (`type="password"`). Default: `false`. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `incompletemessage` | `string` | — | Error when some cells are filled but not all; empty uses default. |
| `arialabel` | `string` | — | Names the row when no visible label is present. |
| `incompleteMessage` | `string` | `""` | Error when some cells are filled but not all; empty uses a default. |
| `ariaLabel` | `string` | `""` | Names the row when no visible label is present. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuOtpChangeDetail` | Committed value change (`detail.value`). |
| `vu-invalid` | `VuOtpInvalidDetail` | When validation messages are recomputed. |
| `vu-clear` | `VuOtpClearDetail` | After `reset()` syncs from `defaultValue`. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `reset` | - Clears cells to `defaultValue` and dispatches `vu-clear`. |
| `focusFirst` | - Focuses the first OTP cell. |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, cells row, hint, and error. |
| `label` | Label element above the OTP row. |
| `cells` | Flex row wrapping all digit cells (`role="group"`). |
| `cell` | One OTP character input. |
| `hint` | Neutral helper text under the row. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `text` | String `label` text when the `label` slot is empty. |

## Types

### `VuOtpChangeDetail`

```ts
{ value: string; }
```

### `VuOtpClearDetail`

```ts
{ value: string; }
```

### `VuOtpInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuOtpRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuOtpSize`

```ts
"sm" | "md" | "lg"
```

### `VuOtpTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuOtpVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/otp
- Markdown: https://velkinui.com/component/otp.md

---

# Radio Group

A radio group component with shared label and validation.

- **Tag:** `vu-radio-group`
- **Slug:** `radio-group`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuRadioGroup` from `@velkin/react/radio-group`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuRadioGroup } from "@velkin/react/radio-group";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `VuRadioGroupOrientation` | `"horizontal"` | `horizontal` (default) wraps members; `vertical` stacks them. |
| `legend` | `string` | `""` | Plain-text in-group caption (muted vs string label); use slot="legend" for markup. |
| `label` | `string` | `""` | Plain-text field label above the group; use slot="label" for markup. |
| `hint` | `string` | `""` | Plain-text helper under the group; use `slot="hint"` for markup. |
| `ariaLabel` | `string` | `""` | Accessible name when there is no visible label or legend. |
| `variant` | `VuRadioVariant` | `"default"` | Forwarded to members that omit their own `variant`. |
| `color` | `VuRadioColor` | `"primary"` | Forwarded to members that omit their own `color`. |
| `tone` | `VuRadioTone` | `"normal"` | Forwarded to members that omit their own `tone`. |
| `size` | `VuRadioSize` | `"md"` | Forwarded to members that omit their own `size`. |
| `name` | `string` | — | Form field name forwarded to every member. Default: `""`. |
| `defaultvalue` | `string` | — | Value restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string \| null` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | `false` | Disables every member while set (releases only attrs this group claimed). |
| `readonly` | `boolean` | `false` | Forwarded to members; blocks selection (inherited from `FormControlBase`). |
| `required` | `boolean` | `false` | When true, `checkValidity` / `reportValidity` fail until one member is selected. |
| `requiredMessage` | `string` | `"This field is required."` | Message for host `valueMissing` when `required` and nothing is selected. |
| `compact` | `boolean` | `false` | Tighter hint and error spacing. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `value` | `string \| undefined` | `undefined` | Selected member `value`; set from JS to control selection. Omit to stay uncontrolled. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuRadioGroupChangeDetail` | After a member is selected; `detail.value` mirrors `value` when controlled. Fired on the group host (not the member). |
| `vu-invalid` | `VuRadioGroupValidationErrorDetail` | When validation messages are recomputed while `validationActive`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - One or more `<vu-radio>` members (other nodes are ignored for forwarding). |
| `label` | Rich field label; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |
| `legend` | Rich legend inside the group; takes precedence over string `legend` when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column that stacks label, group, hint, and error. |
| `label` | Field label wrapper (string `label` or `label` slot). |
| `text` | String `label` when the `label` slot is empty. |
| `base` | `role="radiogroup"` wrapper (legend + default slot). |
| `legend` | In-group caption row; styled quieter than part label. |
| `fields` | Flex container around radios. |
| `hint` | Helper text region (string `hint` or `hint` slot). |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |

## Types

### `string | undefined`

```ts
undefined | string
```

### `VuRadioColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuRadioGroupChangeDetail`

```ts
{ value: string; source: HTMLElement | null; }
```

### `VuRadioGroupOrientation`

```ts
"horizontal" | "vertical"
```

### `VuRadioGroupValidationErrorDetail`

```ts
{ errors: string[]; }
```

### `VuRadioSize`

```ts
"sm" | "md" | "lg"
```

### `VuRadioTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuRadioVariant`

```ts
"outline" | "default" | "soft"
```

## Links

- Docs: https://velkinui.com/component/radio-group
- Markdown: https://velkinui.com/component/radio-group.md

---

# Range

A range slider component for choosing a min-max interval with validation.

- **Tag:** `vu-range`
- **Slug:** `range`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuRange` from `@velkin/react/range`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuRange } from "@velkin/react/range";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Restored on `<form reset>` as `"from,to"` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks thumb dragging (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change the range (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when invalid (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id for label `for` / `aria-*` wiring. |
| `variant` | `VuRangeVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuRangeTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuRangeSize` | `"md"` | Track scale. Default: `"md"`. |
| `radius` | `VuRangeRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the control to the container width. Default: `false`. |
| `compact` | `boolean` | `false` | Tighter label/hint/error spacing. Default: `false`. |
| `from` | `number` | `20` | Lower bound of the selected range. Default: `20`. |
| `to` | `number` | `80` | Upper bound of the selected range. Default: `80`. |
| `min` | `number` | `0` | Minimum selectable value. Default: `0`. |
| `max` | `number` | `100` | Maximum selectable value. Default: `100`. |
| `step` | `number` | `10` | Step interval for snapping. Default: `10`. |
| `prefix` | `string` | `""` | Text before each formatted endpoint. |
| `suffix` | `string` | `""` | Text after each formatted endpoint. |
| `showvalue` | `boolean` | — | Shows the formatted value summary. Default: `true`. |
| `commitonly` | `boolean` | — | Emits `vu-change` on thumb commit only. Default: `false`. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `arialabel` | `string` | — | Names the track when no visible label is present. |
| `showValue` | `boolean` | `true` | Shows the formatted value summary. |
| `commitOnly` | `boolean` | `false` | Emits `vu-change` on thumb commit only. |
| `ariaLabel` | `string` | `""` | Names the track when no visible label is present. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuRangeChangeDetail` | Committed or live range update. |
| `vu-invalid` | `VuRangeInvalidDetail` | When validation messages are recomputed. |
| `vu-clear` | `VuRangeClearDetail` | After `reset()` syncs from `defaultValue`. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `setRange` | - Sets and normalizes the selected range; emits `vu-change`. |
| `reset` | - Restores `defaultValue` and dispatches `vu-clear`. |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, header, track, hint, and error. |
| `label` | Label element above the control. |
| `header` | Row with label and value summary. |
| `control` | Interactive track row (`.range-track`) with variant chrome. |
| `value` | Formatted `from`–`to` summary. |
| `affix` | Prefix or suffix text in the value summary. |
| `highlight` | Selected range segment. |
| `thumb-from` | Lower native `<input type="range">`. |
| `thumb-to` | Upper native `<input type="range">`. |
| `hint` | Neutral helper text under the track. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `text` | String `label` text when the `label` slot is empty. |

## Types

### `VuRangeChangeDetail`

```ts
{ from: number; to: number; }
```

### `VuRangeClearDetail`

```ts
{ from: number; to: number; }
```

### `VuRangeInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuRangeRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuRangeSize`

```ts
"sm" | "md" | "lg"
```

### `VuRangeTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuRangeVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/range
- Markdown: https://velkinui.com/component/range.md

---

# Serial

A serial input component for license keys with group separators.

- **Tag:** `vu-serial`
- **Slug:** `serial`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuSerial` from `@velkin/react/serial`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSerial } from "@velkin/react/serial";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks cell entry (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change cells (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when incomplete (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id for label `for` / `aria-*` wiring. |
| `variant` | `VuSerialVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuSerialTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuSerialSize` | `"md"` | Cell scale. Default: `"md"`. |
| `radius` | `VuSerialRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the cell row to the container width. Default: `false`. |
| `compact` | `boolean` | `false` | Tighter label/hint/error spacing. Default: `false`. |
| `length` | `number` | `10` | Total number of character boxes. Default: `10`. |
| `separator` | `string` | `"-"` | Separator character between groups. Default: `"-"`. |
| `separatorpositions` | `number[]` | — | Cell indices after which a separator is shown (JS-only). |
| `alphanumeric` | `boolean` | `false` | Allows letters in addition to digits. Default: `false`. |
| `value` | `string` | `""` | Canonical serial string (may include separators). Default: `""`. |
| `withseparator` | `boolean` | — | Includes separators in `value` and form submission. Default: `false`. |
| `masked` | `boolean` | `false` | Masks cell glyphs (`type="password"`). Default: `false`. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `incompletemessage` | `string` | — | Error when some cells are filled but not all; empty uses default. |
| `arialabel` | `string` | — | Names the row when no visible label is present. |
| `separatorPositions` | `number[]` | `[3]` | Cell indices after which a separator is inserted (e.g. `[3, 6]`). |
| `withSeparator` | `boolean` | `false` | Includes separators in `value` and form submission. |
| `incompleteMessage` | `string` | `""` | Error when some cells are filled but not all; empty uses a default. |
| `ariaLabel` | `string` | `""` | Names the row when no visible label is present. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuSerialChangeDetail` | Committed value change (`detail.value`). |
| `vu-invalid` | `VuSerialInvalidDetail` | When validation messages are recomputed. |
| `vu-clear` | `VuSerialClearDetail` | After `reset()` syncs from `defaultValue`. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `reset` | - Clears cells to `defaultValue` and dispatches `vu-clear`. |
| `focusFirst` | - Focuses the first serial cell. |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, cells row, hint, and error. |
| `label` | Label element above the serial row. |
| `cells` | Flex row wrapping groups and separators (`role="group"`). |
| `group` | Tight cluster of cells between separators. |
| `separator` | Visual separator glyph between groups. |
| `cell` | One serial character input. |
| `hint` | Neutral helper text under the row. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `text` | String `label` text when the `label` slot is empty. |

## Types

### `VuSerialChangeDetail`

```ts
{ value: string; }
```

### `VuSerialClearDetail`

```ts
{ value: string; }
```

### `VuSerialInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuSerialRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuSerialSize`

```ts
"sm" | "md" | "lg"
```

### `VuSerialTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuSerialVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/serial
- Markdown: https://velkinui.com/component/serial.md

---

# Slider

A slider component for choosing a numeric value with label and validation.

- **Tag:** `vu-slider`
- **Slug:** `slider`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuSlider` from `@velkin/react/slider`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSlider } from "@velkin/react/slider";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks thumb dragging (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change the value (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when invalid (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id for label `for` / `aria-*` wiring. |
| `variant` | `VuSliderVariant` | `"default"` | Field chrome recipe. Default: `"default"`. |
| `tone` | `VuSliderTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuSliderSize` | `"md"` | Track scale. Default: `"md"`. |
| `radius` | `VuSliderRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches the control to the container width. Default: `false`. |
| `compact` | `boolean` | `false` | Tighter label/hint/error spacing. Default: `false`. |
| `min` | `number` | `0` | Minimum selectable value. Default: `0`. |
| `max` | `number` | `100` | Maximum selectable value. Default: `100`. |
| `step` | `number` | `1` | Step interval for snapping. Default: `1`. |
| `value` | `number` | `50` | Snapped slider value. Default: `50`. |
| `displayvalue` | `number` | — | Live visual value while dragging when `commitonly`. |
| `prefix` | `string` | `""` | Text before the formatted value. |
| `suffix` | `string` | `""` | Text after the formatted value. |
| `showvalue` | `boolean` | — | Shows the formatted value summary. Default: `true`. |
| `commitonly` | `boolean` | — | Emits `vu-change` on thumb commit only. Default: `false`. |
| `showerrors` | `boolean` | — | Shows validation after activation (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `arialabel` | `string` | — | Names the track when no visible label is present. |
| `displayValue` | `number` | `50` | Live visual value while dragging when `commitonly`. |
| `showValue` | `boolean` | `true` | Shows the formatted value summary. |
| `commitOnly` | `boolean` | `false` | Emits `vu-change` on thumb commit only. |
| `ariaLabel` | `string` | `""` | Names the track when no visible label is present. |
| `showErrors` | `boolean` | `false` | Shows validation after activation. |
| `validationActive` | `boolean` | `false` | Drives invalid styling after activation. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuSliderChangeDetail` | Committed or live value update. |
| `vu-invalid` | `VuSliderInvalidDetail` | When validation messages are recomputed. |
| `vu-clear` | `VuSliderClearDetail` | After `reset()` syncs from `defaultValue`. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `setValue` | - Sets value after clamp/snap and emits `vu-change`. |
| `reset` | - Restores `defaultValue` and dispatches `vu-clear`. |
| `validateInput` | - Runs validators and syncs validity. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label, header, track, hint, and error. |
| `label` | Label element above the control. |
| `header` | Row with label and value summary. |
| `control` | Interactive track row (`.slider-track`) with variant chrome. |
| `value` | Formatted value summary. |
| `affix` | Prefix or suffix text in the value summary. |
| `highlight` | Accent fill from min to the current value. |
| `thumb-visual` | Visible thumb on the highlight edge. |
| `thumb` | Native `<input type="range">` drag target. |
| `hint` | Neutral helper text under the track. |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `text` | String `label` text when the `label` slot is empty. |

## Types

### `VuSliderChangeDetail`

```ts
{ value: number; }
```

### `VuSliderClearDetail`

```ts
{ value: number; }
```

### `VuSliderInvalidDetail`

```ts
{ errors: string[]; }
```

### `VuSliderRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuSliderSize`

```ts
"sm" | "md" | "lg"
```

### `VuSliderTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuSliderVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/slider
- Markdown: https://velkinui.com/component/slider.md

---

# Switch

A toggle switch component with label, hint, and validation.

- **Tag:** `vu-switch`
- **Slug:** `switch`
- **Category:** Inputs
- **Tier:** MIT
- **React:** `VuSwitch` from `@velkin/react/switch`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSwitch } from "@velkin/react/switch";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Form field name for submit (`name` attr). |
| `defaultvalue` | `string` | — | Value restored on `<form reset>` (`defaultvalue` attr). |
| `formid` | `string` | — | External `<form>` id (`formid` attr). |
| `disabled` | `boolean` | — | Non-interactive; blocks toggle (`disabled` attr). |
| `readonly` | `boolean` | — | Focusable but cannot change checked state (`readonly` attr). |
| `required` | `boolean` | — | Blocks valid submit when unchecked (`required` attr). |
| `requiredmessage` | `string` | — | Custom `valueMissing` message (`requiredmessage` attr). |
| `label` | `string` | `""` | Plain-text label; slotted `label` wins when assigned. |
| `hint` | `string` | `""` | Helper text; `hint` slot wins when assigned. |
| `id` | `string` | `""` | Host id forwarded to the internal input. |
| `value` | `string` | `""` | Form submit token when checked (`value` attr). |
| `color` | `VuSwitchColor` | `"primary"` | Intent palette token for the checked accent. Default: `"primary"`. |
| `tone` | `VuSwitchTone` | `"normal"` | Neutral idle-track weight (`subtle`/`normal`/`strong`). Default: `"normal"`. |
| `size` | `VuSwitchSize` | `"md"` | Track, gap, and label scale. Default: `"md"`. |
| `variant` | `VuSwitchVariant` | `"default"` | Track paint recipe. Default: `"default"`. |
| `arialabel` | `string` | — | Accessible name when no visible label. |
| `compact` | `boolean` | `false` | Tighter hint/error spacing (`compact` attr). Default: `false`. |
| `defaultchecked` | `boolean` | — | Restored by `reset()` / form reset (`defaultchecked` attr). Default: `false`. |
| `showerrors` | `boolean` | — | Shows validation after first blur when `required` (`showerrors` attr). Default: `false`. |
| `validationactive` | `boolean` | — | Drives invalid styling after activation (`validationactive` attr). Default: `false`. |
| `invalid` | `boolean` | `false` | True when last validation found errors (`invalid` attr). Default: `false`. |
| `checked` | `boolean` | — | Checked state (`checked` attr). Default: `false`. |
| `ariaLabel` | `string` | `""` | Inner input accessible name when no string or slotted label (icon-only). |
| `defaultChecked` | `boolean` | `false` | Target checked state for `reset()` and `<form>.reset()`; reflects as `defaultchecked`. |
| `showErrors` | `boolean` | `false` | When true with `required`, shows `requiredMessage` after first blur if unchecked; reflects as `showerrors`. |
| `validationActive` | `boolean` | `false` | After first blur with `showerrors`, drives invalid styling and error text. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuSwitchChangeDetail` | User toggle; `detail.checked` boolean; `detail.value` submit token or boolean. |
| `vu-invalid` | `VuSwitchValidationErrorDetail` | When validation messages are recomputed while `validationActive`. |
| `vu-clear` | `VuSwitchValueClearedDetail` | After `reset()` syncs state from `defaultChecked`. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |
| `hint` | Optional helper copy (HTML); overrides string `hint` when assigned. |
| `error` | Replaces default validation message list when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `check` | - Sets checked to true. |
| `uncheck` | - Sets checked to false. |
| `toggle` | - Flips checked state. |
| `validateInput` | - Runs `required` validation; `vu-form` calls this when aggregating field errors. |
| `reset` | - Resets to `defaultChecked`, clears validation UI, and dispatches `vu-clear`. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column that stacks the control row, optional hint, and optional error. |
| `wrapper` | Row wrapper around the input and label. |
| `input` | The native checkbox input used as the switch control (`role="switch"`). |
| `label` | The label element for the switch row. |
| `track` | The rounded track behind the thumb. |
| `thumb` | The sliding thumb on the track. |
| `hint` | Neutral helper text under the label (string `hint` or `hint` slot). |
| `error-message` | Region for `slot="error"` or stacked default validation lines. |
| `error-line` | One default validation string when `slot="error"` is empty. |
| `text` | String `label` text when the `label` slot is empty. |

## Types

### `VuSwitchChangeDetail`

```ts
{ checked: boolean; value: string | boolean | undefined; }
```

### `VuSwitchColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuSwitchSize`

```ts
"sm" | "md" | "lg"
```

### `VuSwitchTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuSwitchValidationErrorDetail`

```ts
{ errors: string[]; }
```

### `VuSwitchValueClearedDetail`

```ts
{ value: string; checked: boolean; }
```

### `VuSwitchVariant`

```ts
"outline" | "default" | "soft"
```

## Links

- Docs: https://velkinui.com/component/switch
- Markdown: https://velkinui.com/component/switch.md

---

# Text Editor

A rich text editor component with formatting toolbar and fonts.

- **Tag:** `vu-text-editor`
- **Slug:** `text-editor`
- **Category:** Inputs
- **Tier:** Pro
- **React:** `VuTextEditor` from `@velkin/react-pro/text-editor`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuTextEditor } from "@velkin/react-pro/text-editor";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | `""` | Text content. |
| `editorStyle` | `Partial` | `{}` | External style seed merged into the editor. |
| `presets` | `VuTextEditorPresets` | `{}` | Preset lists for toolbar selects. |
| `useLocalFonts` | `boolean` | `false` | Enables `queryLocalFonts()` on font field focus. |
| `variant` | `VuTextEditorVariant` | `"default"` | Field chrome recipe. |
| `tone` | `VuTextEditorTone` | `"normal"` | Neutral chrome weight. |
| `size` | `VuTextEditorSize` | `"md"` | Toolbar + textarea scale. |
| `radius` | `VuTextEditorRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `block` | `boolean` | `false` | Stretches to container width. |
| `disabled` | `boolean` | `false` | Disables editing and toolbar controls. |
| `readonly` | `boolean` | `false` | Keeps focus but blocks edits. |
| `label` | `string` | `""` | Plain-text label fallback. |
| `placeholder` | `string` | `""` | Textarea placeholder. |
| `clearlabel` | `string` | `""` | Clear text action label override. |
| `resetstylelabel` | `string` | `""` | Reset styles action label override. |
| `arialabel` | `string` | `""` | Accessible name when no visible label is provided. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuTextEditorChangeDetail` | When `value` or `style` changes. |

## Slots

| Name | Description |
| --- | --- |
| `label` | Rich label markup; takes precedence over string `label` when assigned. |

## Methods

| Name | Description |
| --- | --- |
| `getValue` | - Returns current text content. |
| `setValue` | - Sets text content. |
| `getStyle` | - Returns the active editor style object. |
| `focus` | - Focuses the textarea. |

## CSS parts

| Name | Description |
| --- | --- |
| `field` | Column stacking label and editor shell. |
| `label` | Visible label element. |
| `container` | Bordered editor shell (toolbar + body). |
| `toolbar` | Formatting toolbar row. |
| `toolbar-divider` | Hairline between toolbar and editor body. |
| `toolbar-select` | Toolbar `vu-combobox` controls. |
| `body` | Textarea container region. |
| `textarea` | Editable textarea surface. |
| `actions` | Reset action cluster. |

## Types

### `VuTextEditorChangeDetail`

```ts
{ value: string; style: VuTextEditorStyle; source: VuTextEditorChangeSource; }
```

### `VuTextEditorPresets`

```ts
{ fontFamilies?: VuTextEditorOption[]; fontSizes?: VuTextEditorOption[]; fontWeights?: VuTextEditorOption[]; textAligns?: VuTextEditorOption[]; colors?: VuTextEditorOption[]; backgrounds?: VuTextEditorOption[]; textDecorations?: VuTextEditorOption[]; lineHeights?: VuTextEditorOption[]; initialStyle?: Partial<VuTextEditorStyle>; }
```

### `VuTextEditorRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuTextEditorSize`

```ts
"sm" | "md" | "lg"
```

### `VuTextEditorTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuTextEditorVariant`

```ts
"outline" | "default" | "underline"
```

## Links

- Docs: https://velkinui.com/component/text-editor
- Markdown: https://velkinui.com/component/text-editor.md

---

# Data display

# Avatar

An avatar component with image, initials, icon, or custom content.

- **Tag:** `vu-avatar`
- **Slug:** `avatar`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuAvatar` from `@velkin/react/avatar`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAvatar } from "@velkin/react/avatar";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `""` | Image URL. |
| `name` | `string` | `""` | Derives initials and default `alt`. |
| `alt` | `string` | `""` | Image accessible name; defaults to `name`. |
| `size` | `VuAvatarSize` | `"md"` | Overall dimension. Default: `"md"`. |
| `radius` | `VuAvatarRadius` | `"full"` | Corner radius. Default: `"full"`. |
| `color` | `VuAvatarColor` | `"default"` | Fallback surface intent. Default: `"default"`. |
| `bordered` | `boolean` | `false` | Colored ring around the avatar. Default: `false`. |
| `disabled` | `boolean` | `false` | Dims and disables pointer events. Default: `false`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Custom fallback when the image is absent or fails. |

## CSS parts

| Name | Description |
| --- | --- |
| `avatar` | Outer surface. |
| `image` | The `<img>` element. |
| `fallback` | Slot, initials, or default icon wrapper. |

## Types

### `VuAvatarColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuAvatarRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuAvatarSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/avatar
- Markdown: https://velkinui.com/component/avatar.md

---

# Avatar Group

An avatar group component that stacks overlapping avatars.

- **Tag:** `vu-avatar-group`
- **Slug:** `avatar-group`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuAvatarGroup` from `@velkin/react/avatar-group`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAvatarGroup } from "@velkin/react/avatar-group";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` | `0` | Maximum avatars shown; `0` shows all. Default: `0`. |
| `total` | `number` | `0` | Explicit total when extras are outside the slot. Default: `0`. |
| `size` | `VuAvatarSize` | `"md"` | Uniform size forwarded to children. Default: `"md"`. |
| `radius` | `VuAvatarRadius` | `"full"` | Uniform radius forwarded to children. Default: `"full"`. |
| `spacing` | `VuAvatarGroupSpacing` | `"md"` | Overlap density. Default: `"md"`. |
| `bordered` | `boolean` | `true` | Forwards bordered ring to children. Default: `true`. |
| `disabled` | `boolean` | `false` | Disables the group and forwards to children. Default: `false`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - One or more `<vu-avatar>` children. |
| `overflow` | Custom `+N` overflow indicator. |

## CSS parts

| Name | Description |
| --- | --- |
| `group` | Flex container for avatars and overflow tile. |
| `overflow` | Auto-rendered `+N` avatar tile. |

## Types

### `VuAvatarGroupSpacing`

```ts
"sm" | "md" | "lg"
```

### `VuAvatarRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuAvatarSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/avatar-group
- Markdown: https://velkinui.com/component/avatar-group.md

---

# Badge

A badge component for counts, status dots, and overlay marks.

- **Tag:** `vu-badge`
- **Slug:** `badge`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuBadge` from `@velkin/react/badge`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuBadge } from "@velkin/react/badge";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | `""` | Count or short text fallback. |
| `max` | `number` | `99` | Cap numeric values to `N+`; `0` disables. Default: `99`. |
| `dot` | `boolean` | `false` | Pure-dot mode. Default: `false`. |
| `size` | `VuBadgeSize` | `"md"` | Pill scale (`sm`\|`md`\|`lg`; shared core with button). Default: `"md"`. |
| `color` | `VuBadgeColor` | `"danger"` | Intent palette; defaults to `"danger"` for count/alert marks. Default: `"danger"`. |
| `placement` | `VuBadgePlacement` | `"top-right"` | Corner anchor. Default: `"top-right"`. |
| `offset` | `string` | `""` | CSS-length nudge from the anchor corner. |
| `bordered` | `boolean` | `true` | Colored ring with halo cutout. Default: `true`. |
| `show` | `boolean` | `true` | Explicit visibility toggle. Default: `true`. |
| `hideOnZero` | `boolean` | `false` | Auto-hides when numeric `value` is 0 (`hideonzero` attr). Default: `false`. |
| `processing` | `boolean` | `false` | Outward pulse animation. Default: `false`. |
| `disabled` | `boolean` | `false` | Dims the badge. Default: `false`. |
| `label` | `string` | `""` | Accessible name override. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Anchor content the badge overlays. |
| `mark` | Custom badge glyph; ignored when `dot` is true. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Wrapper holding anchor and badge. |
| `badge` | Overlaid pill or dot. |

## Types

### `VuBadgeColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuBadgePlacement`

```ts
"top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center"
```

### `VuBadgeSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/badge
- Markdown: https://velkinui.com/component/badge.md

---

# Chip

A chip component for tags and filters with dismiss or toggle actions.

- **Tag:** `vu-chip`
- **Slug:** `chip`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuChip` from `@velkin/react/chip`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuChip } from "@velkin/react/chip";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `""` | Plain-text fallback when the default slot has no meaningful content. |
| `value` | `string` | `""` | Stable id for lists, filters, and `vu-close` / `vu-change` detail. |
| `removable` | `boolean` | `false` | Shows dismiss control; `close()` fires cancelable `vu-close`. Default: `false`. |
| `color` | `VuChipColor` | `"default"` | Intent token only (no arbitrary CSS colors). Default: `"default"`. |
| `radius` | `VuChipRadius` | `"full"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `"full"`. |
| `size` | `VuChipSize` | `"md"` | Padding/type scale; `sm`\|`md`\|`lg` match button, `xs`/`xl` are density extras. Default: `"md"`. |
| `iconstart` | `string` | — | Iconify id for the leading icon. |
| `iconend` | `string` | — | Iconify id for the trailing icon. |
| `loading` | `boolean` | `false` | Loading overlay; hides label chrome like `vu-button`. Default: `false`. |
| `disabled` | `boolean` | `false` | Disables interaction. Default: `false`. |
| `variant` | `VuChipVariant` | `"soft"` | Paint recipe. Default: `"soft"`. |
| `selected` | `boolean` | `false` | Toggle/filter selected state; sets `aria-pressed` when interactive. Default: `false`. |
| `interactive` | `boolean` | `false` | Renders the label as a `<button>` when `href` is empty. Default: `false`. |
| `iconOnly` | `boolean` | `false` | Square 1:1 chip; hides the label and uses it as `aria-label`. Default: `false`. |
| `href` | `string` | `""` | When set, renders the label as an `<a>` instead of static text. |
| `target` | `string` | `""` | Anchor target when `href` is set. |
| `rel` | `string` | `""` | Anchor rel when `href` is set. |
| `closelabel` | `string` | — | Accessible name for dismiss; empty uses the locale catalog. |
| `arialabel` | `string` | — | Accessible name override for the interactive label control. |
| `iconStart` | `string` | `""` | Iconify id for the leading icon. |
| `iconEnd` | `string` | `""` | Iconify id for the trailing icon. |
| `closeLabel` | `string` | `""` | Accessible name for dismiss; empty uses the locale catalog. |
| `ariaLabel` | `string` | `""` | Accessible name override for the interactive label control. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-close` | `VuChipCloseDetail` | Cancelable; default action removes the host. |
| `vu-change` | `VuChipChangeDetail` | When `interactive` and the user toggles `selected`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Primary label; when empty, the string `label` prop is shown. |
| `start` | Leading content before icons and label. |
| `end` | Trailing content after label and before dismiss. |

## Methods

| Name | Description |
| --- | --- |
| `close` | - Fires cancelable `vu-close`; removes the host when not prevented. |

## CSS parts

| Name | Description |
| --- | --- |
| `chip` | Outer pill surface. |
| `control` | Label region (span, button, or anchor depending on mode). |
| `start` | Leading slot wrapper. |
| `end` | Trailing slot wrapper. |
| `icon` | Each leading or trailing Iconify icon. |
| `close` | Dismiss control when `removable` (same UI as vu-alert `close`). |
| `loading-overlay` | Loading scrim. |
| `loading-spinner` | Spinner node. |

## Types

### `VuChipChangeDetail`

```ts
{ selected: boolean; value: string; label: string; }
```

### `VuChipCloseDetail`

```ts
{ label: string; value: string; reason: VuChipCloseReason; }
```

### `VuChipColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuChipRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuChipSize`

```ts
"sm" | "md" | "lg" | "xs" | "xl"
```

### `VuChipVariant`

```ts
"solid" | "outline" | "soft" | "ghost" | "dot"
```

## Links

- Docs: https://velkinui.com/component/chip
- Markdown: https://velkinui.com/component/chip.md

---

# Data Table

A data table component with sorting, filtering, and selection.

- **Tag:** `vu-data-table`
- **Slug:** `data-table`
- **Category:** Data display
- **Tier:** Pro
- **React:** `VuDataTable` from `@velkin/react-pro/data-table`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuDataTable } from "@velkin/react-pro/data-table";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `TableColumnDef[]` | `[]` | Column tree with optional nested headers. Default: `[]`. |
| `defaultColumnDef` | `TableDefaultColumnDef` | `{}` | Defaults merged into every column. Default: `{}`. |
| `rowData` | `TableRow[]` | `[]` | Row records; each row requires a string id. Default: `[]`. |
| `dataProvider` | `TableDataProvider \| null` | `null` | Alternate row source via `fetch`. Client ops by default; `serverSideOperations: true` for SSRM. Default: `null`. |
| `lazyColumns` | `boolean` | `false` | With `dataProvider`, request in-view (+ pinned/sort/filter/group) column keys. Default: `false`. |
| `rowKey` | `string` | `"id"` | Field used as the stable row id. Default: `"id"`. |
| `showIndexColumn` | `boolean` | `false` | Synthetic 1-based row-index column pinned left. Default: `false`. |
| `defaultExpandedGroupLevels` | `number \| null` | `null` | Auto-collapse groups deeper than this; `null` keeps all expanded. Default: `null`. |
| `singleExpandedRow` | `boolean` | `false` | Accordion expand — only one data row open. Default: `false`. |
| `cellSelection` | `boolean` | `false` | Click/drag cell range selection and copy. Default: `false`. |
| `keyboardNavigation` | `boolean` | `false` | Arrow/Tab/Home-style active cell; typeahead jump when `cellEditing` is off. Default: `false`. |
| `cellEditing` | `boolean` | `false` | In-cell edit (F2, Enter, type-to-replace). Printable keys typeahead-jump when this is off. Default: `false`. |
| `searching` | `boolean` | `false` | Quick-filter search bar. Default: `false`. |
| `sorting` | `boolean` | `false` | Column header sort controls. Default: `false`. |
| `pagination` | `boolean` | `false` | Footer pagination controls. Default: `false`. |
| `filtering` | `boolean` | `false` | Per-column floating filter row. Default: `false`. |
| `advancedFiltering` | `boolean` | `false` | Expression filter bar in the header chrome. Default: `false`. |
| `grouping` | `boolean` | `false` | Row grouping with group-by chip row. Default: `false`. |
| `columnVisibility` | `boolean` | `false` | Columns sidebar pane and header hide action. Default: `false`. |
| `columnReorder` | `boolean` | `false` | Drag-reorder leaf column headers. Default: `false`. |
| `rowDrag` | `boolean` | `false` | Drag-reorder data rows. Default: `false`. |
| `totalBar` | `boolean` | `false` | Footer aggregate total bar. Default: `false`. |
| `columnMenu` | `boolean` | `false` | Per-column header overflow menu. Default: `false`. |
| `pivot` | `boolean` | `false` | Pivot builder in the columns sidebar. Default: `false`. |
| `expandedRows` | `boolean` | `false` | Expandable row detail panels. Default: `false`. |
| `gridlines` | `boolean` | `false` | Show vertical column separator lines. Default: `false`. |
| `rowSelection` | `VuDataTableRowSelection \| null` | `null` | Selection state; omit to disable selection UI. Default: `null`. |
| `tone` | `VuDataTableTone` | `"normal"` | Neutral surface weight for row and header chrome. Default: `"normal"`. |
| `sort` | `TableSortRule[]` | `[]` | Controlled multi-column sort rules. Default: `[]`. |
| `columnFilters` | `Record` | `{}` | Active per-column filters keyed by field. Default: `{}`. |
| `quickFilterText` | `string` | `""` | Controlled quick-filter text. Default: `""`. |
| `advancedFilterQuery` | `string` | `""` | Controlled advanced filter expression. Default: `""`. |
| `page` | `number` | `1` | Current page index (1-based). Default: `1`. |
| `pageSize` | `number` | `25` | Rows per page. Default: `25`. |
| `pageSizeOptions` | `DataTablePageSizeOption[]` | `[10, 25, 50, 100, "all"]` | Page-size choices for the footer menu. Default: `[10, 25, 50, 100, "all"]`. |
| `groupBy` | `string[]` | `[]` | Column fields for multi-level row grouping. Default: `[]`. |
| `collapsedGroupKeys` | `string[]` | `[]` | Collapsed group row keys. Default: `[]`. |
| `groupColumnLabel` | `string` | `"Group"` | Header for the auto-group column. Default: `"Group"`. |
| `height` | `string` | `"360px"` | Viewport block size for the virtualized body. Default: `"360px"`. |
| `loading` | `boolean` | `false` | Shows a loading overlay over the grid viewport. Default: `false`. |
| `rowModel` | `TableRowModel` | — | Row store; overrides rowData when set. `lazyRowModel()` auto-attaches `createRowIndexProvider`. |
| `columnModel` | `TableColumnModel` | — | Column store; overrides columns when set. |
| `columnWidths` | `Record` | `{}` | Per-column width overrides keyed by field. Default: `{}`. |
| `columnResize` | `boolean` | `false` | Drag resize handles on leaf headers. Default: `false`. |
| `expandedRowIds` | `string[]` | `[]` | Expanded data-row ids. Default: `[]`. |
| `expandedRowRenderer` | `VuDataTableExpandedRowRenderer \| null` | `null` | Detail panel renderer for expanded rows. Default: `null`. |
| `expandedRowHeight` | `number` | `120` | Estimated detail row block size before measurement. Default: `120`. |
| `pivotConfig` | `TablePivotConfig \| null` | `null` | Pivot field assignment. Default: `null`. |
| `pivotEnabled` | `boolean` | `true` | Renders the pivot layout instead of the flat grid. Default: `true`. |
| `collapsedPivotKeys` | `string[]` | `[]` | Collapsed pivot group row keys. Default: `[]`. |
| `pivotRowSort` | `TablePivotRowSort` | `{}` | Per row-dimension pivot sort state. Default: `{}`. |
| `pivotColumnSortDirection` | `TablePivotColumnSortDirection` | `"asc"` | Hierarchical sort for pivot column keys. Default: `"asc"`. |
| `aggregation` | `TableEngineState["aggregation"]` | `"sum"` | Default numeric aggregation for group subtotals. Default: `"sum"`. |
| `aggregators` | `TableAggregatorRegistry` | `{}` | Custom reducers referenced from column aggregation. Default: `{}`. |
| `extraSidebarPanes` | `DataTableSidebarPaneDefinition[]` | `[]` | Custom sidebar panes after built-in columns and filters. Default: `[]`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-quick-filter` | `VuDataTableQuickFilterDetail` | Quick-filter text changes. |
| `vu-advanced-filter` | `VuDataTableAdvancedFilterDetail` | Advanced filter expression changes. |
| `vu-sort` | `VuDataTableSortDetail` | Sort rule changes. |
| `vu-page` | `VuDataTablePageChangeDetail` | Pagination changes. |
| `vu-filter` | `VuDataTableFilterDetail` | Column filter changes. |
| `vu-selection` | `VuDataTableSelectionChangeDetail` | Row selection changes. |
| `vu-column-width` | `VuDataTableColumnWidthDetail` | Column width overrides. |
| `vu-group` | `VuDataTableGroupDetail` | Group-by or collapse changes. |
| `vu-pivot` | `VuDataTablePivotDetail` | Pivot config changes. |
| `vu-expanded-row` | `VuDataTableExpandedRowDetail` | Expanded row id changes. |
| `vu-column-visibility` | `VuDataTableColumnVisibilityDetail` | Column visibility changes. |
| `vu-column-reorder` | `VuDataTableColumnReorderDetail` | Column tree reorder. |
| `vu-row-reorder` | `VuDataTableRowReorderDetail` | Row data reorder. |
| `vu-data-provider-error` | `VuDataTableDataProviderErrorDetail` | Fired when `dataProvider.fetch` (or a secondary hook) rejects. |
| `vu-cell-selection` | `VuDataTableCellSelectionDetail` | Active cell / range selection changed. |
| `vu-cell-change` | `VuDataTableCellChangeDetail` | A cell value was committed. |

## Slots

| Name | Description |
| --- | --- |
| `header-actions` | Extra controls inline at the end of the native header toolbar row. |
| `footer-actions` | Extra controls inline in the native pagination footer bar. |
| `header` | Extra banner above the grid chrome. |
| `footer` | Extra banner below the pagination bar. |
| `empty` | Empty-state content when the current view has no rows. |
| `loading` | Loading overlay content; replaces the default message. |

## Methods

| Name | Description |
| --- | --- |
| `getSnapshot` | - Returns the current read-only view snapshot from the table engine. |
| `applyState` | - Applies a partial host + engine state patch. |
| `exportCsv` | - Serializes the current view to CSV. |
| `copySelection` | - Copies the selected cells (or current view) as TSV. Pass `{ nested: true }` for stacked headers. |
| `commitCellValue` | - Writes one cell and emits `vu-cell-change`. |

## CSS parts

| Name | Description |
| --- | --- |
| `header-chrome` | Search and group-by controls above column headers. |
| `header` | Column header scroll region. |
| `header-cell` | One header cell. |
| `search` | Search field wrapper in the header chrome. |
| `search-input` | Native search text input. |
| `search-clear` | Clear-search button shown when a query is present. |
| `advanced-filter` | Advanced filter bar (`vu-advanced-filter`) in the header chrome. |
| `advanced-filter-field` | Advanced filter input field wrapper. |
| `advanced-filter-input` | Advanced filter expression input. |
| `advanced-filter-clear` | Clear advanced filter button. |
| `advanced-filter-builder` | Visual builder toggle button. |
| `advanced-filter-suggestions` | Type-ahead suggestions list. |
| `advanced-filter-popover` | Visual builder popover surface. |
| `group-by` | Group-by chip row in the header chrome. |
| `group-by-chips` | Active group-by chips container; drop header columns here. |
| `group-by-chip` | One grouped column chip; drag to reorder. |
| `group-by-chip-remove` | Remove button on a group-by chip. |
| `header-actions` | Inline action controls in the header toolbar row. |
| `header-menu-trigger` | Three-dot column menu button on leaf headers. |
| `header-column-menu` | Popover panel for column menu actions. |
| `filter-row` | Per-column floating filter row below headers. |
| `filter-cell` | One floating filter cell (input + advanced filter menu). |
| `filter-button` | Advanced filter icon button in a filter cell. |
| `filter-panel` | Advanced filter dropdown panel for one column. |
| `footer` | Pagination footer below the grid. |
| `footer-info` | Row range summary in the footer. |
| `footer-pagination` | Centered pagination bar region. |
| `footer-controls` | Page size menu and footer action controls (end-aligned). |
| `footer-actions` | Inline action controls in the pagination footer bar. |
| `page-size` | Rows-per-page dropdown. |
| `sidebar` | Right-edge sidebar shell (tab rail + panes). |
| `sidebar-tabs` | Vertical tab rail for sidebar panes. |
| `sidebar-tab` | One sidebar tab button. |
| `sidebar-pane-columns` | Columns pane (visibility checklist and pivot controls). |
| `sidebar-pane-filters` | Filters pane. |
| `pivot-zone-available` | Field palette in the columns pane pivot builder. |
| `pivot-zone-row` | Row dimension drop zone. |
| `pivot-zone-column` | Column dimension drop zone. |
| `pivot-zone-value` | Value dimension drop zone. |
| `pivot-field` | One draggable field in the palette. |
| `pivot-chip` | Assigned field chip in a drop zone. |
| `pivot-mode-switch` | Pivot on/off switch in the columns pane. |
| `body` | Virtualized body scrollport. |
| `cell` | One body cell. |
| `header-banner` | Extra `header` slot region above the grid chrome. |
| `footer-banner` | Extra `footer` slot region below pagination. |
| `empty` | Empty-state overlay when the view has no rows. |
| `cell-editor` | Native input shown while a cell is being edited. |
| `filter-chips` | Active column-filter chips in the header chrome. |
| `filter-chip` | One active filter chip. |
| `filter-chip-remove` | Clear button on an active filter chip. |
| `bulk-bar` | Selection summary bar. |
| `bulk-bar-count` | Selected row count label. |
| `bulk-bar-clear` | Clear-selection control. |

## Types

### `number | null`

```ts
null | number
```

### `TableAggregatorRegistry`

```ts
{ [x: string]: TableAggregatorFn; }
```

### `TableColumnModel`

```ts
{ mode: "tree"; columns: TableColumnDef[]; } | { mode: "range"; count: number; width: number; headerName?: string | ((index: number) => string); type?: TableColumnType; sortable?: boolean; searchable?: boolean; pinnedLeft?: number; pinnedRight?: number; totalBarColumnKeys?: string[]; }
```

### `TableDataProvider | null`

```ts
null | TableDataProvider
```

### `TableDefaultColumnDef`

```ts
{ type?: TableColumnType | undefined; visible?: boolean | undefined; searchable?: boolean | undefined; sortable?: boolean | undefined; width?: number | undefined; flex?: number | undefined; minWidth?: number | undefined; maxWidth?: number | undefined; pinned?: TablePin | undefined; dataAlign?: TableAlign | undefined; headerAlign?: TableAlign | undefined; aggregation?: TableAggregationKind | undefined; headerAggregation?: TableHeaderAggregationSpec | undefined; headerAggregationByLevel?: TableHeaderAggregationByLevel | undefined; cellRenderer?: TableColumnCellRenderer | undefined; editable?: boolean | undefined; valueGetter?: TableColumnValueGetter | undefined; valueFormatter?: TableColumnValueFormatter | undefined; }
```

### `TableEngineState["aggregation"]`

```ts
string
```

### `TablePivotColumnSortDirection`

```ts
"asc" | "desc"
```

### `TablePivotConfig | null`

```ts
null | { rowDimensions: readonly string[]; columnDimensions: readonly string[]; values: readonly TablePivotValueField[]; }
```

### `TablePivotRowSort`

```ts
{ [x: string]: TablePivotRowSortEntry; }
```

### `TableRowModel`

```ts
{ mode: "client"; rows: TableRow[]; index?: TableRowIndexProvider; } | { mode: "lazy"; rowCount: number; getRowId: (sourceRowIndex: number) => string; getValue: (sourceRowIndex: number, field: string) => unknown; index?: TableRowIndexProvider; }
```

### `VuDataTableAdvancedFilterDetail`

```ts
{ query: string; snapshot: TableViewSnapshot; }
```

### `VuDataTableCellChangeDetail`

```ts
{ rowId: string; field: string; value: unknown; row: TableRow | null; snapshot: TableViewSnapshot; }
```

### `VuDataTableCellSelectionDetail`

```ts
{ activeCell: VuDataTableCellCoord | null; selectedCells: string[]; snapshot: TableViewSnapshot; }
```

### `VuDataTableColumnReorderDetail`

```ts
{ columns: TableColumnDef[]; snapshot: TableViewSnapshot; }
```

### `VuDataTableColumnVisibilityDetail`

```ts
{ columns: TableColumnDef[]; snapshot: TableViewSnapshot; }
```

### `VuDataTableColumnWidthDetail`

```ts
{ columnWidths: Record<string, number>; snapshot: TableViewSnapshot; }
```

### `VuDataTableExpandedRowDetail`

```ts
{ expandedRowIds: string[]; snapshot: TableViewSnapshot; }
```

### `VuDataTableExpandedRowRenderer | null`

```ts
null | (row: TableRow, context: VuDataTableExpandedRowRendererContext) => unknown
```

### `VuDataTableFilterDetail`

```ts
{ columnFilters: Record<string, TableColumnFilter>; snapshot: TableViewSnapshot; }
```

### `VuDataTableGroupDetail`

```ts
{ groupBy: string[]; collapsedGroupKeys: string[]; columns?: TableColumnDef[]; snapshot: TableViewSnapshot; }
```

### `VuDataTablePageChangeDetail`

```ts
VuDataTablePageDetail & { snapshot: TableViewSnapshot; }
```

### `VuDataTablePivotDetail`

```ts
{ pivotEnabled?: boolean; pivotConfig?: TablePivotConfig; collapsedPivotKeys?: string[]; pivotRowSort?: TablePivotRowSort; pivotColumnSortDirection?: TablePivotColumnSortDirection; snapshot: TableViewSnapshot; }
```

### `VuDataTableQuickFilterDetail`

```ts
{ query: string; snapshot: TableViewSnapshot; }
```

### `VuDataTableRowReorderDetail`

```ts
{ rowData: TableRow[]; snapshot: TableViewSnapshot; }
```

### `VuDataTableRowSelection | null`

```ts
null | { mode: TableSelectionMode; selectAll?: boolean; selectedIds?: string[]; excludedIds?: string[]; }
```

### `VuDataTableSelectionChangeDetail`

```ts
VuDataTableSelectionDetail & { snapshot: TableViewSnapshot; }
```

### `VuDataTableSortDetail`

```ts
{ sort: TableSortRule[]; snapshot: TableViewSnapshot; }
```

### `VuDataTableTone`

```ts
"subtle" | "normal" | "strong"
```

## Links

- Docs: https://velkinui.com/component/data-table
- Markdown: https://velkinui.com/component/data-table.md

---

# Divider

A divider component for horizontal or vertical layout separation.

- **Tag:** `vu-divider`
- **Slug:** `divider`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuDivider` from `@velkin/react/divider`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuDivider } from "@velkin/react/divider";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `VuDividerDirection` | `"horizontal"` | Divider orientation. Default: `"horizontal"`. |
| `inset` | `boolean` | `false` | Indents the line from the start/end edges. Default: `false`. |
| `size` | `VuDividerSize` | `"md"` | Hairline thickness scale. Default: `"md"`. |

## CSS parts

| Name | Description |
| --- | --- |
| `divider` | The `role="separator"` line element. |

## Types

### `VuDividerDirection`

```ts
"horizontal" | "vertical"
```

### `VuDividerSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/divider
- Markdown: https://velkinui.com/component/divider.md

---

# File Viewer

A file viewer component for previewing uploaded or linked files.

- **Tag:** `vu-file-viewer`
- **Slug:** `file-viewer`
- **Category:** Data display
- **Tier:** Pro
- **React:** `VuFileViewer` from `@velkin/react-pro/file-viewer`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuFileViewer } from "@velkin/react-pro/file-viewer";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `filepairId` | `string` | `""` | Paired picker id that matches `filepairid` on `<vu-file-picker>`. |
| `srcSet` | `string[]` | `[]` | Direct URLs to preview before paired picker files. |
| `emptyText` | `string` | `""` | Empty-state message shown when no previews are available. |
| `layout` | `VuFileViewerLayout` | `"grid"` | Preview layout mode (`grid` or `list`). |
| `density` | `VuFileViewerDensity` | `"default"` | Preview density (`compact`, `default`, `comfortable`); matches `<vu-file-picker density>`. |
| `gridMinWidth` | `number` | `320` | Minimum grid column width (px) when auto columns are used. |
| `gridColumns` | `number` | `0` | Fixed grid column count (`0` uses auto-fill). |
| `gap` | `number` | `16` | Spacing between preview cards (px). |
| `showViewButton` | `boolean` | `true` | Shows per-file full-size preview action. |
| `viewLabel` | `string` | `""` | Label for the full-size preview action. |
| `showRemoveFromPicker` | `boolean` | `true` | Shows remove action for files from a paired picker. |
| `removeLabel` | `string` | `""` | Label for the remove-from-selection action. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - No slots are exposed; file previews are rendered internally. |

## Methods

| Name | Description |
| --- | --- |
| `refreshFromPair` | Reloads preview files from the paired `vu-file-picker`. |
| `clear` | Clears loaded files and resets preview state. |

## CSS parts

| Name | Description |
| --- | --- |
| `panel` | Root preview panel. |
| `previews-root` | Container for all preview cards (grid or list). |
| `file-item` | Outer card (container query root for responsive list layout). |
| `file-item-layout` | Inner flex row/column: preview + header. |
| `file-header` | File name and plain-text meta line. |
| `preview-stage` | Preview surface outer region (contains type chrome + viewport). |
| `preview-toolbar` | Per-kind label row (icon + uppercase type) above the preview media. |
| `preview-viewport` | Inner area that holds `img`, `video`, `iframe`, `pre`, etc. |
| `preview` | Alias of `preview-stage`. |
| `meta` | Plain-text detail line under the file name. |
| `img` | Image preview (direct child of preview-stage). |
| `video` | Video preview. |
| `iframe` | PDF preview. |
| `audio` | Audio preview. |
| `text` | Text preview (`pre`). |
| `model-viewer` | 3D preview (`vu-model-viewer` for GLB/GLTF/STL/OBJ). |
| `other` | “No inline preview” card when type is unsupported. |
| `fullscreen-root` | Fixed full-viewport preview layer. |
| `fullscreen-backdrop` | Dim + blur; click closes. |
| `fullscreen-bar` | Top row: filename (start) + close (end). |
| `fullscreen-close` | Close control. |
| `fullscreen-content` | The file preview only (no inner type chrome). |
| `download` | Download action link. |
| `view-button` | Opens the full-size preview dialog for that file. |
| `remove-button` | Removes this file from the paired `vu-file-picker` selection. |

## Types

### `VuFileViewerDensity`

```ts
"default" | "compact" | "comfortable"
```

### `VuFileViewerLayout`

```ts
"grid" | "list"
```

## Links

- Docs: https://velkinui.com/component/file-viewer
- Markdown: https://velkinui.com/component/file-viewer.md

---

# Flow

A flow diagram component with nodes, edges, pan, zoom, and selection.

- **Tag:** `vu-flow`
- **Slug:** `flow`
- **Category:** Data display
- **Tier:** Pro
- **React:** `VuFlow` from `@velkin/react-pro/flow`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuFlow } from "@velkin/react-pro/flow";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `VuFlowNodeModel[]` | `[]` | Graph nodes. |
| `edges` | `VuFlowEdgeModel[]` | `[]` | Graph edges. |
| `autofitLive` | `boolean` | `false` | Fit view when content changes. Default: `false`. |
| `locked` | `boolean` | `false` | Disables pan, drag, and connect. Default: `false`. |
| `withControls` | `boolean` | `false` | Shows zoom/fit/lock controls. Default: `false`. |
| `withMiniMap` | `boolean` | `false` | Shows navigation minimap. Default: `false`. |
| `virtualizeThreshold` | `number` | `0` | Virtualize nodes above this count; `0` disables. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-select` | `VuFlowSelectDetail` | Selection changed. |
| `vu-drag` | `VuFlowDragDetail` | Node drag phase (`start`/`move`/`end`). |
| `vu-node-add` | `VuFlowNodeAddDetail` | Node added via `addNode()`. |
| `vu-connect` | `VuFlowConnectDetail` | Connect gesture or edge create. |
| `vu-context` | `VuFlowContextDetail` | Right-click; call `preventDefault()` to suppress built-in menu. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - `<vu-flow-node>` and `<vu-flow-edge-overlay>` children. |
| `context-menu` | Prefer `<vu-flow-context-menu>`; custom content also works. |

## Methods

| Name | Description |
| --- | --- |
| `fitView` | - Fit all nodes into the viewport. |
| `zoomIn` | - Zoom in one step. |
| `zoomOut` | - Zoom out one step. |
| `setLocked` | - Toggle or set the locked state. |
| `addNode` | - Add a node and fire `vu-node-add`. |
| `addEdge` | - Add an edge and fire `vu-connect`. |
| `deleteSelected` | - Remove selected nodes/edges from the graph. |
| `clearSelection` | - Clear the current selection. |
| `getSelection` | - Return currently selected nodes and edges. |
| `autoLayout` | - Run layered layout (topo + barycentric) and animate node positions. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Grab/pan surface. |
| `nodes` | Node layer host. |
| `pool` | Reserved (culling is in-place; kept for API stability). |
| `overlays` | Edge-overlay layer host. |
| `controls` | Zoom/fit/lock controls cluster. |
| `minimap` | Minimap panel. |
| `context-menu` | Context menu panel. |

## Types

### `VuFlowConnectDetail`

```ts
{ phase: VuFlowGesturePhase; sourceId: string; sourceSide: VuFlowSide | null; targetId?: string | null; targetSide?: VuFlowSide | null; valid?: boolean; created?: boolean; edge?: VuFlowEdgeModel; reason?: string; x?: number; y?: number; }
```

### `VuFlowContextDetail`

```ts
{ target: VuFlowContextTarget; clientX: number; clientY: number; graphX: number; graphY: number; node?: VuFlowNodeModel; edge?: VuFlowEdgeModel; nodes: VuFlowNodeModel[]; edges: VuFlowEdgeModel[]; }
```

### `VuFlowDragDetail`

```ts
{ phase: VuFlowGesturePhase; node: VuFlowNodeModel; event?: MouseEvent; }
```

### `VuFlowNodeAddDetail`

```ts
{ node: VuFlowNodeModel; }
```

### `VuFlowSelectDetail`

```ts
{ nodes: VuFlowNodeModel[]; edges: VuFlowEdgeModel[]; }
```

## Links

- Docs: https://velkinui.com/component/flow
- Markdown: https://velkinui.com/component/flow.md

---

# Icon

An icon component with offline sets, lazy loading, and SVG fallback.

- **Tag:** `vu-icon`
- **Slug:** `icon`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuIcon` from `@velkin/react/icon`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuIcon } from "@velkin/react/icon";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `string` | `""` | Icon name in `prefix:icon-name` format. |
| `width` | `VuIconSizeValue` | `""` | Icon width. Default: `1em` when height is also unset. |
| `height` | `VuIconSizeValue` | `""` | Icon height. Default: `1em` when width is also unset. |
| `color` | `string` | `"currentColor"` | Icon color. Default: `"currentColor"`. |
| `inline` | `boolean` | `false` | Inline alignment tweak for text contexts. Default: `false`. |
| `flip` | `VuIconFlip` | `""` | Flip transform descriptor. |
| `hFlip` | `boolean` | `false` | Horizontal flip shortcut. Default: `false`. |
| `vFlip` | `boolean` | `false` | Vertical flip shortcut. Default: `false`. |
| `rotate` | `VuIconRotateValue` | `"0"` | Rotation descriptor (quarter turns or `deg`). |
| `lazy` | `boolean` | `false` | Defers loading until visible. Default: `false`. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Fallback `<svg>` when remote/local icon data is unavailable. |

## Methods

| Name | Description |
| --- | --- |
| `registerLocalSet` | - Registers a local Iconify set for offline/custom usage. |
| `registerLocalIcon` | - Registers a single local icon override. |

## CSS parts

| Name | Description |
| --- | --- |
| `icon` | Icon container wrapping the SVG or slot. |

## Types

### `VuIconFlip`

```ts
"" | "horizontal" | "vertical" | "horizontal,vertical"
```

### `VuIconRotateValue`

```ts
string | number
```

### `VuIconSizeValue`

```ts
string | number
```

## Links

- Docs: https://velkinui.com/component/icon
- Markdown: https://velkinui.com/component/icon.md

---

# Image

An image component with responsive srcset and optional auto sizes.

- **Tag:** `vu-image`
- **Slug:** `image`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuImage` from `@velkin/react/image`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuImage } from "@velkin/react/image";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `""` | Primary image source URL. |
| `alt` | `string` | `""` | Alternative text; empty marks decorative. |
| `srcset` | `string` | `""` | Responsive source set string. |
| `sizes` | `string` | `""` | Responsive sizes string. |
| `autoSizes` | `boolean` | `false` | Computes `sizes` from host width (`autosizes` attr). Default: `false`. |
| `fit` | `VuImageFit` | `"cover"` | Object-fit preset. Default: `"cover"`. |
| `loading` | `VuImageLoading` | `"lazy"` | Native loading hint. Default: `"lazy"`. |
| `decoding` | `VuImageDecoding` | `"async"` | Native decoding hint. Default: `"async"`. |

## CSS parts

| Name | Description |
| --- | --- |
| `img` | The underlying `<img>` element. |
| `placeholder` | Empty-state block when `src` is blank. |

## Types

### `VuImageDecoding`

```ts
"auto" | "async" | "sync"
```

### `VuImageFit`

```ts
"none" | "cover" | "contain" | "fill" | "scale-down"
```

### `VuImageLoading`

```ts
"lazy" | "eager"
```

## Links

- Docs: https://velkinui.com/component/image
- Markdown: https://velkinui.com/component/image.md

---

# Kanban

A kanban board component with columns, cards, and drag-and-drop.

- **Tag:** `vu-kanban`
- **Slug:** `kanban`
- **Category:** Data display
- **Tier:** Pro
- **React:** `VuKanban` from `@velkin/react-pro/kanban`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuKanban } from "@velkin/react-pro/kanban";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `VuKanbanColumnModel[]` | `[]` | Column definitions (data mode). |
| `cards` | `VuKanbanCardModel[]` | `[]` | Cards ordered within each column by array appearance. |
| `dragEnabled` | `boolean` | `true` | Enables HTML5 drag-and-drop. Default: `true`. |
| `mutable` | `boolean` | `true` | Updates `cards` / slotted DOM after move when true. Default: `true`. |
| `placeholder` | `string` | `""` | Empty-column placeholder (overrides localized default). |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-move` | `VuKanbanMoveDetail` | Fired when a card is moved. |
| `vu-change` | `VuKanbanChangeDetail` | Fired with the next cards array. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Optional slotted `vu-kanban-column` children (rich composition mode). |
| `empty` | Shown when there are no columns and no cards. |

## Methods

| Name | Description |
| --- | --- |
| `refreshLayout` | - Requests a board reflow/repaint. |
| `moveCard` | - Programmatically move a card (same path as drop/keyboard). |

## CSS parts

| Name | Description |
| --- | --- |
| `board` | Root board container (horizontal scroll). |

## Types

### `VuKanbanChangeDetail`

```ts
{ cards: VuKanbanCardModel[]; }
```

### `VuKanbanMoveDetail`

```ts
{ cardId: string; fromColumnId: string; toColumnId: string; fromIndex: number; toIndex: number; }
```

## Links

- Docs: https://velkinui.com/component/kanban
- Markdown: https://velkinui.com/component/kanban.md

---

# List

A list component with selection, type-ahead, and keyboard navigation.

- **Tag:** `vu-list`
- **Slug:** `list`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuList` from `@velkin/react/list`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuList } from "@velkin/react/list";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selection` | `VuListSelectionMode` | `"none"` | Selection mode for child rows. Default: `"none"`. |
| `selectedValues` | `string[]` | — | Controlled selection tokens; omit for uncontrolled mode. |
| `defaultSelectedValues` | `string[]` | `[]` | Initial selection when uncontrolled. Default: `[]`. |
| `size` | `VuListSize` | `"md"` | Default row density. Default: `"md"`. |
| `tone` | `VuListTone` | `"normal"` | Neutral surface weight for the list shell. Default: `"normal"`. |
| `dense` | `boolean` | `false` | Compact rows on the list and items. Default: `false`. |
| `autofocus` | `boolean` | `false` | Focuses the first row after first render. Default: `false`. |
| `ariaLabel` | `string` | `""` | Accessible name when there is no visible list label. Default: `""`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuListChangeDetail` | When selection changes (`detail.selectedValues`). |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Default slot for `<vu-listitem>` children. |

## Methods

| Name | Description |
| --- | --- |
| `focusListItem` | - Focuses a focusable item by index among non-subheader rows. |
| `getItems` | - Returns slotted `<vu-listitem>` instances in document order. |
| `handleRowKeydown` | - Keyboard handler invoked by each row (internal). |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Bordered list surface wrapping the default slot. |

## Types

### `VuListChangeDetail`

```ts
{ selectedItems: VuListitem[]; selectedValues: string[]; }
```

### `VuListSelectionMode`

```ts
"none" | "single" | "multiple"
```

### `VuListSize`

```ts
"sm" | "md" | "lg"
```

### `VuListTone`

```ts
"subtle" | "normal" | "strong"
```

## Links

- Docs: https://velkinui.com/component/list
- Markdown: https://velkinui.com/component/list.md

---

# Model Viewer

A 3D model viewer component with orbit controls and staging options.

- **Tag:** `vu-model-viewer`
- **Slug:** `model-viewer`
- **Category:** Data display
- **Tier:** Pro
- **React:** `VuModelViewer` from `@velkin/react-pro/model-viewer`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuModelViewer } from "@velkin/react-pro/model-viewer";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `""` | Model source URL. |
| `alt` | `string` | `"3D model"` | Accessible description text. |
| `poster` | `string \| null` | `null` | Poster image URL shown before reveal. |
| `reveal` | `VuModelViewerReveal` | `"auto"` | Reveal mode for poster/model transition. |
| `loading` | `VuModelViewerLoading` | `"auto"` | Loading behavior hint. |
| `cameraControls` | `boolean` | `true` | Enables orbit controls. |
| `cameraOrbit` | `string` | `"0deg 75deg 105%"` | Camera orbit string (theta phi radius). |
| `cameraTarget` | `string` | `"auto auto auto"` | Camera target string. |
| `autoRotate` | `boolean` | `false` | Enables continuous auto-rotation. |
| `pmiSrc` | `string` | `""` | Sidecar PMI JSON source. |
| `pmiVisible` | `boolean` | `true` | Toggles PMI visibility. |
| `loadingLabel` | `string` | `""` | Override for loading poster / progress accessible copy. |
| `interactionPromptLabel` | `string` | `""` | Override for the orbit/zoom hint text. |
| `fullscreenLabel` | `string` | `""` | Override for enter-fullscreen accessible name. |
| `exitFullscreenLabel` | `string` | `""` | Override for exit-fullscreen accessible name. |
| `showPmiLabel` | `string` | `""` | Override for show-PMI button copy. |
| `hidePmiLabel` | `string` | `""` | Override for hide-PMI button copy. |
| `unlimitedOrbit` | `boolean` | `false` | When true, orbit has no angle limits so the model can rotate freely on all axes. |
| `axesIndicator` | `VuModelViewerAxesIndicator` | `"none"` | Show X/Y/Z axis lines in a corner for orientation reference. Use "none" to hide. |
| `axesIndicatorSpace` | `VuModelViewerAxesSpace` | `"world"` | `world` = screen-projected world axes; `model` = local axes after `heightAxis` (CAD / Z-up). |
| `environment` | `string` | `""` | HDR environment map URL (.hdr — loaded via RGBELoader). |
| `skyboxImage` | `string` | `""` | Equirectangular HDR for background (.hdr, loaded via RGBELoader). |
| `disableContextMenu` | `boolean` | `false` | When true, right-click context menu on the canvas is disabled. |
| `withFullscreenButton` | `boolean` | `false` | Shows a fullscreen toggle in the corner. |
| `withPmiToggleButton` | `boolean` | `false` | Shows a built-in PMI visibility toggle in the corner. |
| `dracoDecoderPath` | `string` | `""` | Optional DRACO decoder base path for compressed glTF. |
| `ktx2TranscoderPath` | `string` | `""` | Optional KTX2/Basis transcoder path for glTF textures. |
| `texture` | `string` | `""` | Comma-separated base-color map URLs mapped onto materials in order (cycles if fewer). |
| `pmiWorldLeaderLength` | `number` | `40` | Default leader length in **model units** for simple leaders (`leader.leader_points` not used). |
| `pmiDefaultLineColor` | `string` | `"var(--vu-color-foreground)"` | PMI line/arrow/datum color; supports `var(--token)` resolved via computed style. |
| `pmiDefaultTextColor` | `string` | `""` | PMI label fill when JSON omits `textColor`; empty uses the resolved line color. |
| `pmiLabelOrientation` | `PmiLabelOrientation` | `"billboard"` | PMI label orientation: `billboard` (face camera) or `plane` (annotation normal). |
| `heightAxis` | `VuModelViewerHeightAxis` | `"z"` | Model up axis: `y` (glTF/Blender) or `z` (CAD); `z` rotates so Z is vertical in the viewer. |
| `format` | `VuModelViewerFormat` | `""` | Explicit format (`gltf` \| `stl` \| `obj`) when URL/MIME sniffing is insufficient. |
| `preserveCameraOnSrcChange` | `boolean` | `false` | Keep orbit/target and interaction state when `src` changes instead of reframing. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-load` | `Event` | Fired when the model has finished loading. |
| `vu-error` | `VuModelViewerErrorDetail` | Fired when model loading fails. |
| `vu-progress` | `VuModelViewerProgressDetail` | Fired during model loading. |
| `vu-camera` | `VuModelViewerCameraChangeDetail` | Fired when camera orbit or target changes. |
| `vu-poster` | `VuModelViewerPosterDetail` | Fired when the poster is hidden and the model is revealed. |
| `vu-visibility` | `VuModelViewerModelVisibilityDetail` | Fired when model visibility changes. |
| `vu-pmi` | `VuModelViewerPmiVisibilityChangeDetail` | Fired when PMI visibility is toggled. |

## Slots

| Name | Description |
| --- | --- |
| `poster` | Content shown while the model is loading (e.g. placeholder image or spinner). |

## Methods

| Name | Description |
| --- | --- |
| `resetView` | Restores default camera orbit/target and reapplies camera transforms. |

## CSS parts

| Name | Description |
| --- | --- |
| `container` | Wrapper around the canvas and chrome overlays. |
| `poster` | Loading/poster overlay. |
| `interaction-prompt` | Orbit/zoom interaction hint. |
| `progress` | Determinate load progress bar. |
| `fullscreen-button` | Fullscreen toggle control. |
| `pmi-toggle-button` | PMI visibility toggle control. |

## Types

### `PmiLabelOrientation`

```ts
"billboard" | "plane"
```

### `string | null`

```ts
null | string
```

### `VuModelViewerAxesIndicator`

```ts
"none" | "top-right" | "top-left" | "bottom-right" | "bottom-left"
```

### `VuModelViewerAxesSpace`

```ts
"world" | "model"
```

### `VuModelViewerCameraChangeDetail`

```ts
{ source: string; }
```

### `VuModelViewerErrorDetail`

```ts
unknown
```

### `VuModelViewerFormat`

```ts
"" | "gltf" | "stl" | "obj"
```

### `VuModelViewerHeightAxis`

```ts
"y" | "z"
```

### `VuModelViewerLoading`

```ts
"auto" | "lazy" | "eager"
```

### `VuModelViewerModelVisibilityDetail`

```ts
{ visible: boolean; }
```

### `VuModelViewerPmiVisibilityChangeDetail`

```ts
{ visible: boolean; }
```

### `VuModelViewerPosterDetail`

```ts
{ dismissed: true; }
```

### `VuModelViewerProgressDetail`

```ts
{ totalProgress: number; reason?: string; }
```

### `VuModelViewerReveal`

```ts
"auto" | "manual"
```

## Links

- Docs: https://velkinui.com/component/model-viewer
- Markdown: https://velkinui.com/component/model-viewer.md

---

# Tree

A tree component for browsing folders and files with virtualization.

- **Tag:** `vu-tree`
- **Slug:** `tree`
- **Category:** Data display
- **Tier:** Pro
- **React:** `VuTree` from `@velkin/react-pro/tree`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuTree } from "@velkin/react-pro/tree";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `VuTreeItem[]` | `[]` | Directory data with unique `id` and `label`. Default: `[]`. |
| `value` | `string \| null` | `null` | Currently open file id. Default: `null`. |
| `expandedIds` | `string[]` | — | Controlled expanded folder ids; omit for uncontrolled `item.expanded`. |
| `filterText` | `string` | `""` | Case-insensitive label filter. Default: `""`. |
| `noResultsLabel` | `string` | `""` | Fallback when filter matches no rows; defaults to a localized label. |
| `filterDebounceMs` | `number` | `150` | Delay before applying `filterText` to large trees. Default: `150`. |
| `expandIcon` | `"ion:chevron-down"` | `"ion:chevron-down"` | Iconify name for expanded folders. Default: chevron-down. |
| `collapseIcon` | `"ion:chevron-forward"` | `"ion:chevron-forward"` | Iconify name for collapsed folders. Default: chevron-forward. |
| `size` | `VuTreeSize` | `"md"` | Row density preset. Default: `"md"`. |
| `itemHeight` | `number` | — | Virtual row height in px; defaults to the `size` preset (sm 28, md 32, lg 36). |
| `variant` | `VuTreeVariant` | `"explorer"` | `explorer` borderless sidebar or `panel` card. Default: `"explorer"`. |
| `withIcons` | `boolean` | `true` | Auto file/folder icons when nodes omit `icon`. Default: `true`. |
| `withLines` | `boolean` | `false` | Show guide lines between nodes. Default: `false`. |
| `showSize` | `boolean` | `true` | Show trailing file size when nodes include `size`. Default: `true`. |
| `withFolderFirstSort` | `boolean` | `false` | Sort folders before files at each level. Default: `false`. |
| `autoExpandParent` | `boolean` | `true` | Expand ancestors while filtering. Default: `true`. |
| `itemDrag` | `VuTreeDragMode` | `"off"` | Row drag mode: `off`, `reorder`, `reparent`, or `both`. Default: `"off"`. |
| `lazyLoad` | `VuTreeLazyLoadFn` | — | Async children fetch when a folder expands. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-activate` | `VuTreeActivateDetail` | When a file row is activated. |
| `vu-expand` | `VuTreeExpandDetail` | When a folder row expands. |
| `vu-collapse` | `VuTreeCollapseDetail` | When a folder row collapses. |
| `vu-contextmenu` | `VuTreeContextMenuDetail` | When a row receives `contextmenu`. |
| `vu-dragstart` | `VuTreeDragStartDetail` | When a row drag starts. |
| `vu-reorder` | `VuTreeReorderDetail` | When a row is reordered among siblings. |
| `vu-move` | `VuTreeMoveDetail` | When a row is reparented or dropped into a folder. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Default slot for additional tree content. |
| `no-results` | Custom body when `filterText` matches no rows. |

## Methods

| Name | Description |
| --- | --- |
| `expandAll` | Expands all folders. |
| `collapseAll` | Collapses all folders. |
| `focusNode` | Focuses a visible node by flattened index. |
| `scrollToItem` | Scrolls a visible node into view by id. |
| `focusItemById` | Moves roving focus and scrolls a visible node into view. |

## CSS parts

| Name | Description |
| --- | --- |
| `tree` | The outer scrolling tree wrapper. |
| `item-wrapper` | Wrapper for each virtualized row. |
| `item` | Clickable row container for a node. |
| `indent` | Indent gutter grouping ancestor guide columns. |
| `indent-guide` | One ancestor-depth vertical guide column. |
| `switcher` | Chevron column on expandable folder rows; omitted on file rows when `withlines`. |
| `content` | Label column between icon and trailing meta. |
| `item-label` | Text label of a node. |
| `trailing` | Fixed-width trailing column (badge + file size). |
| `item-size` | File size text inside the trailing column. |
| `item-badge` | Git-style status badge before file size. |
| `item-icon-left` | Leading file/folder icon. |
| `expand-button` | Expand/collapse chevron or loading spinner. |
| `no-results` | Filter empty-state region. |
| `no-results-label` | Default no-results text when the slot is empty. |
| `drop-indicator` | Insertion line or folder highlight shown during row drag. |

## Types

### `string | null`

```ts
null | string
```

### `VuTreeActivateDetail`

```ts
{ item: VuTreeItem; value: string; }
```

### `VuTreeCollapseDetail`

```ts
{ item: VuTreeItem; value: string; }
```

### `VuTreeContextMenuDetail`

```ts
{ item: VuTreeItem; value: string; originalEvent: MouseEvent; }
```

### `VuTreeDragMode`

```ts
"both" | "off" | "reorder" | "reparent"
```

### `VuTreeDragStartDetail`

```ts
{ item: VuTreeItem; value: string; }
```

### `VuTreeExpandDetail`

```ts
{ item: VuTreeItem; value: string; }
```

### `VuTreeLazyLoadFn`

```ts
(item: VuTreeItem) => Promise<VuTreeItem[]>
```

### `VuTreeMoveDetail`

```ts
{ item: VuTreeItem; value: string; fromParentId: string | null; toParentId: string | null; fromIndex: number; toIndex: number; position: VuTreeDropPosition; }
```

### `VuTreeReorderDetail`

```ts
{ item: VuTreeItem; value: string; parentId: string | null; fromIndex: number; toIndex: number; position: "before" | "after"; }
```

### `VuTreeSize`

```ts
"sm" | "md" | "lg"
```

### `VuTreeVariant`

```ts
"explorer" | "panel"
```

## Links

- Docs: https://velkinui.com/component/tree
- Markdown: https://velkinui.com/component/tree.md

---

# Video

A video player component with custom overlay controls.

- **Tag:** `vu-video`
- **Slug:** `video`
- **Category:** Data display
- **Tier:** MIT
- **React:** `VuVideo` from `@velkin/react/video`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuVideo } from "@velkin/react/video";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | `""` | Primary video URL. |
| `poster` | `string` | `""` | Poster image URL. |
| `fit` | `VuVideoFit` | `"cover"` | Object-fit preset. Default: `"cover"`. |
| `preload` | `VuVideoPreload` | `"metadata"` | Native preload hint. Default: `"metadata"`. |
| `autoplay` | `boolean` | `false` | Starts playback when allowed. Default: `false`. |
| `loop` | `boolean` | `false` | Restarts when the clip ends. Default: `false`. |
| `muted` | `boolean` | `false` | Mutes audio output. Default: `false`. |
| `playsinline` | `boolean` | `true` | Sets `playsinline` on mobile. Default: `true`. |
| `controls` | `boolean` | `true` | Renders the custom control bar. Default: `true`. |
| `playLabel` | `string` | `""` | Play accessible name (`playlabel` attr). |
| `pauseLabel` | `string` | `""` | Pause accessible name (`pauselabel` attr). |
| `muteLabel` | `string` | `""` | Mute accessible name (`mutelabel` attr). |
| `unmuteLabel` | `string` | `""` | Unmute accessible name (`unmutelabel` attr). |
| `fullscreenLabel` | `string` | `""` | Enter-fullscreen accessible name (`fullscreenlabel` attr). |
| `exitFullscreenLabel` | `string` | `""` | Exit-fullscreen accessible name (`exitfullscreenlabel` attr). |
| `seekLabel` | `string` | `""` | Seek slider accessible name (`seeklabel` attr). |
| `volumeLabel` | `string` | `""` | Volume slider accessible name (`volumelabel` attr). |
| `label` | `string` | `""` | Player accessible name. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-play` | `VuVideoPlaybackDetail` | When playback starts. |
| `vu-pause` | `VuVideoPlaybackDetail` | When playback pauses. |
| `vu-seek` | `VuVideoSeekDetail` | When the user commits a seek. |
| `vu-ended` | `VuVideoPlaybackDetail` | When playback ends. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Optional `<source>` or `<track>` elements for the inner `<video>`. |

## Methods

| Name | Description |
| --- | --- |
| `play` | - Starts playback. |
| `pause` | - Pauses playback. |
| `togglePlay` | - Toggles play and pause. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Root layout shell. |
| `video` | Native `<video>` element. |
| `controls` | Full-screen overlay chrome. |
| `top-bar` | Top-right volume and fullscreen actions. |
| `volume-shell` | Volume button and popover anchor. |
| `volume-popover` | Vertical volume slider panel. |
| `volume-rail` | Rotated slider layout wrapper. |
| `volume` | Vertical volume range input. |
| `bottom-bar` | Bottom scrubber row. |
| `seek` | Progress seek slider. |
| `play` | Center play or pause button. |
| `time-current` | Elapsed time readout. |
| `time-remaining` | Remaining time readout. |
| `mute` | Volume button. |
| `fullscreen` | Fullscreen toggle. |

## Types

### `VuVideoFit`

```ts
"none" | "cover" | "contain" | "fill"
```

### `VuVideoPlaybackDetail`

```ts
{ currentTime: number; }
```

### `VuVideoPreload`

```ts
"auto" | "none" | "metadata"
```

### `VuVideoSeekDetail`

```ts
{ currentTime: number; previousTime: number; }
```

## Links

- Docs: https://velkinui.com/component/video
- Markdown: https://velkinui.com/component/video.md

---

# Feedback

# Alert

An alert component with intent colors, variants, and optional dismiss.

- **Tag:** `vu-alert`
- **Slug:** `alert`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuAlert` from `@velkin/react/alert`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAlert } from "@velkin/react/alert";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `VuAlertColor` | `"default"` | Intent driving surface color. Default: `"default"`. |
| `variant` | `VuAlertVariant` | `"soft"` | Surface paint recipe. Default: `"soft"`. |
| `size` | `VuAlertSize` | `"md"` | Padding, gap, and font scale. Default: `"md"`. |
| `heading` | `string` | `""` | Heading text above the body. |
| `message` | `string` | `""` | Body text when the default slot is empty. |
| `icon` | `string \| null` | `null` | Iconify name; `null` derives from `color`, `""` disables. |
| `removable` | `boolean` | `false` | Shows a dismiss button. Default: `false`. |
| `closeLabel` | `string` | `""` | Dismiss accessible name (`closelabel` attr). |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-close` | `VuAlertCloseDetail` | Cancelable before exit animation. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Body content when `message` is empty. |
| `heading` | Heading content when `heading` is empty. |
| `icon` | Custom leading icon. |
| `actions` | Trailing buttons or links. |

## Methods

| Name | Description |
| --- | --- |
| `close` | - Programmatic dismiss; fires `vu-close` then animates out. |

## CSS parts

| Name | Description |
| --- | --- |
| `alert` | Outer surface container. |
| `icon` | Leading icon wrapper. |
| `stack` | Heading and body column. |
| `heading` | Heading text element. |
| `body` | Body region wrapper. |
| `message` | Body paragraph when `message` is set. |
| `actions` | Trailing controls cluster. |
| `close` | Dismiss button when `removable`. |

## Types

### `string | null`

```ts
null | string
```

### `VuAlertCloseDetail`

```ts
{ heading: string; message: string; reason: VuAlertCloseReason; }
```

### `VuAlertColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuAlertSize`

```ts
"sm" | "md" | "lg"
```

### `VuAlertVariant`

```ts
"solid" | "outline" | "soft" | "ghost"
```

## Links

- Docs: https://velkinui.com/component/alert
- Markdown: https://velkinui.com/component/alert.md

---

# Dialog

A dialog component with region slots, focus trap, and backdrop.

- **Tag:** `vu-dialog`
- **Slug:** `dialog`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuDialog` from `@velkin/react/dialog`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuDialog } from "@velkin/react/dialog";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the dialog is visible. Default: `false`. |
| `closable` | `boolean` | `false` | Shows a dismiss control in the corner. Default: `false`. |
| `closeLabel` | `string` | `""` | Accessible name for the dismiss control; empty uses locale catalog. Default: `""`. |
| `ariaLabel` | `string` | `""` | Accessible name when the header slot is empty. Default: `""`. |
| `variant` | `VuDialogVariant` | `"elevated"` | Surface paint recipe. Default: `"elevated"`. |
| `tone` | `VuDialogTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuDialogSize` | `"md"` | Padding scale for header, body, and footer (`sm`/`md`/`lg`). Default: `"md"`. |
| `radius` | `VuDialogRadius` | `"md"` | Panel corner preset (`sm`/`md`/`lg`; Role C′ omits `none`/`full`). Default: `"md"`. |
| `divider` | `boolean` | `false` | Hairlines between shown regions. Default: `false`. |
| `persistent` | `boolean` | `false` | Blocks backdrop and Escape close. Default: `false`. |
| `closeOnEsc` | `boolean` | `true` | Escape emits `vu-close` when topmost. Default: `true`. |
| `maxWidth` | `string` | `""` | Optional CSS max-width; empty keeps `auto`. Default: `""`. |
| `maxHeight` | `string` | `""` | Optional CSS max-height; empty keeps `auto`. Default: `""`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-close` | `VuDialogCloseDetail` | Cancelable close intent; parent sets `open` false when not prevented. |
| `vu-open` | `void` | When the dialog begins opening. |
| `vu-afteropen` | `void` | After the open animation finishes. |
| `vu-afterclose` | `void` | After the close animation finishes. |

## Slots

| Name | Description |
| --- | --- |
| `header` | Title or toolbar row at the top. |
| `body` | Main content region. |
| `footer` | Action buttons at the bottom. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Sets `open` to true. |
| `hide` | - Sets `open` to false. |
| `toggle` | - Toggles `open`. |
| `focus` | - Focuses the dialog element. |

## CSS parts

| Name | Description |
| --- | --- |
| `dialog` | Native `<dialog>` surface. |
| `close-button` | Dismiss control when `closable`. |
| `header` | Header slot wrapper. |
| `header-divider` | Hairline below the header when `divider` is set. |
| `body` | Body slot wrapper. |
| `footer-divider` | Hairline above the footer when `divider` is set. |
| `footer` | Footer slot wrapper. |

## Types

### `VuDialogCloseDetail`

```ts
{ reason: VuDialogCloseReason; }
```

### `VuDialogRadius`

```ts
"sm" | "md" | "lg"
```

### `VuDialogSize`

```ts
"sm" | "md" | "lg"
```

### `VuDialogTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuDialogVariant`

```ts
"outline" | "elevated" | "soft" | "ghost" | "filled"
```

## Links

- Docs: https://velkinui.com/component/dialog
- Markdown: https://velkinui.com/component/dialog.md

---

# Drawer

A drawer component with slide-in panel, backdrop, and focus trap.

- **Tag:** `vu-drawer`
- **Slug:** `drawer`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuDrawer` from `@velkin/react/drawer`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuDrawer } from "@velkin/react/drawer";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the drawer is visible. Default: `false`. |
| `closable` | `boolean` | `false` | Shows a dismiss control on the panel. Default: `false`. |
| `closeLabel` | `string` | `""` | Accessible name for the dismiss control; empty uses locale catalog. Default: `""`. |
| `ariaLabel` | `string` | `""` | Accessible name when the header slot is empty. Default: `""`. |
| `side` | `VuDrawerSide` | `"left"` | Edge the panel slides in from. Default: `"left"`. |
| `variant` | `VuDrawerVariant` | `"elevated"` | Surface paint recipe. Default: `"elevated"`. |
| `tone` | `VuDrawerTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuDrawerSize` | `"md"` | Padding scale for header, body, and footer. Default: `"md"`. |
| `radius` | `VuDrawerRadius` | `"md"` | Panel corner preset (`sm`/`md`/`lg`; Role C′ omits `none`/`full`). Default: `"md"`. |
| `divider` | `boolean` | `false` | Hairlines between shown regions. Default: `false`. |
| `persistent` | `boolean` | `false` | Blocks backdrop and Escape close. Default: `false`. |
| `closeOnEsc` | `boolean` | `true` | Escape emits `vu-close` when topmost. Default: `true`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-close` | `VuDrawerCloseDetail` | Cancelable close intent; parent sets `open` false when not prevented. |
| `vu-open` | `void` | When the drawer begins opening. |
| `vu-afteropen` | `void` | After the open transition finishes. |
| `vu-afterclose` | `void` | After the close transition finishes. |

## Slots

| Name | Description |
| --- | --- |
| `header` | Top region (title or toolbar). |
| `body` | Main scrollable content. |
| `footer` | Bottom actions region. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Sets `open` to true. |
| `hide` | - Sets `open` to false. |
| `toggle` | - Toggles `open`. |
| `focus` | - Focuses the panel container. |

## CSS parts

| Name | Description |
| --- | --- |
| `overlay` | Backdrop behind the panel. |
| `panel` | Sliding surface. |
| `close-button` | Dismiss control when `closable`. |
| `header` | Header slot wrapper. |
| `header-divider` | Hairline below the header when `divider` is set. |
| `body` | Body slot wrapper. |
| `footer-divider` | Hairline above the footer when `divider` is set. |
| `footer` | Footer slot wrapper. |

## Types

### `VuDrawerCloseDetail`

```ts
{ reason: VuDrawerCloseReason; }
```

### `VuDrawerRadius`

```ts
"sm" | "md" | "lg"
```

### `VuDrawerSide`

```ts
"left" | "right"
```

### `VuDrawerSize`

```ts
"sm" | "md" | "lg"
```

### `VuDrawerTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuDrawerVariant`

```ts
"outline" | "elevated" | "soft" | "ghost" | "filled"
```

## Links

- Docs: https://velkinui.com/component/drawer
- Markdown: https://velkinui.com/component/drawer.md

---

# Notification

A notification component that renders the toast viewport.

- **Tag:** `vu-notification`
- **Slug:** `notification`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuNotification` from `@velkin/react/notification`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuNotification } from "@velkin/react/notification";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `VuNotificationPosition` | `"bottom-end"` | Screen corner or center for the toast region. Default: `"bottom-end"`. |
| `layout` | `VuNotificationLayout` | `"list"` | List or stack presentation. Default: `"list"`. |
| `variant` | `VuNotificationVariant` | `"flat"` | Status surface recipe (`flat`\|`soft`\|`solid`\|`bordered`). Default: `"flat"`. |
| `notifications` | `NotificationItemInternal[]` | `[]` | Current toast items. Default: `[]`. |
| `defaultDuration` | `number` | `4000` | Auto-dismiss ms when item duration is omitted; `0` disables. Default: `4000`. |
| `visibleToasts` | `number` | `3` | Collapsed stack layers shown before overflow. Default: `3`. |
| `maxVisible` | `number` | `5` | Max simultaneous toasts before oldest are dropped. Default: `5`. |
| `removable` | `boolean` | `true` | Shows per-toast dismiss controls. Default: `true`. |
| `mergeDuplicates` | `boolean` | `false` | Merges duplicate toasts and increments count. Default: `false`. |
| `closeLabel` | `string` | `""` | Accessible name for dismiss; empty uses locale catalog. Default: `""`. |
| `offset` | `string` | `""` | Viewport inset override (CSS length). Default: `""`. |
| `gap` | `string` | `""` | List gap override (CSS length). Default: `""`. |
| `withProgress` | `boolean` | `false` | Shows auto-dismiss countdown bar on timed toasts. Default: `false`. |
| `withPauseOnHover` | `boolean` | `false` | Pauses auto-dismiss while the list is hovered. Default: `false`. |
| `withPauseWhenHidden` | `boolean` | `true` | Pauses auto-dismiss while the document is hidden. Default: `true`. |
| `withExpandOnClick` | `boolean` | `false` | Pins stack expansion after clicking the pile. Default: `false`. |
| `withOverflowCount` | `boolean` | `false` | Shows overflow count badge in stack layout. Default: `false`. |
| `withSwipeDismiss` | `boolean` | `false` | Enables swipe-to-dismiss on each toast. Default: `false`. |
| `paused` | `boolean` | `false` | Reflects when auto-dismiss timers are paused. Default: `false`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-queue` | `VuNotificationQueueDetail` | When a toast is queued. |
| `vu-remove` | `VuNotificationRemoveDetail` | When a toast is removed. |
| `vu-clear-all` | `VuNotificationClearAllDetail` | When all toasts are cleared. |

## Methods

| Name | Description |
| --- | --- |
| `addNotification` | - Queues a toast; returns its id. |
| `updateNotification` | - Patches an existing toast (promise flow). |
| `removeNotification` | - Dismisses a toast by id. |
| `clearNotifications` | - Dismisses every toast. |
| `show` | - Opens the popover when items exist. |
| `hide` | - Closes the popover. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Root wrapper. |
| `anchor` | Invisible viewport anchor for popover positioning. |
| `panel` | Popover panel listing toasts. |
| `list` | Vertical list or stack grid of toast items. |
| `item` | Individual toast surface. |
| `media` | Optional leading image. |
| `row` | Icon + text row. |
| `icon` | Leading status icon. |
| `spinner` | Loading indicator for promise toasts. |
| `copy` | Title and message column. |
| `title` | Toast title. |
| `message` | Toast body copy. |
| `count` | Duplicate merge badge. |
| `action` | Optional action button. |
| `body` | Custom toast body when `content` is provided. |
| `close` | Per-toast dismiss control. |
| `progress` | Auto-dismiss countdown bar. |
| `overflow` | Hidden-toast count badge in stack layout. |

## Types

### `VuNotificationClearAllDetail`

```ts
{ [x: string]: never; }
```

### `VuNotificationLayout`

```ts
"stack" | "list"
```

### `VuNotificationPosition`

```ts
"top-center" | "bottom-start" | "bottom-end" | "top-start" | "top-end" | "bottom-center"
```

### `VuNotificationQueueDetail`

```ts
{ item: VuNotificationItem; }
```

### `VuNotificationRemoveDetail`

```ts
{ id: number; }
```

### `VuNotificationVariant`

```ts
"solid" | "flat" | "soft" | "bordered"
```

## Links

- Docs: https://velkinui.com/component/notification
- Markdown: https://velkinui.com/component/notification.md

---

# Overlay

An overlay component with backdrop and centered content slot.

- **Tag:** `vu-overlay`
- **Slug:** `overlay`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuOverlay` from `@velkin/react/overlay`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuOverlay } from "@velkin/react/overlay";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the overlay is visible. Default: `false`. |
| `persistent` | `boolean` | `false` | Blocks backdrop and Escape close. Default: `false`. |
| `closeOnEsc` | `boolean` | `true` | Escape emits `vu-close` when topmost. Default: `true`. |
| `backdropblur` | `boolean` | `false` | Blurs content behind the scrim. Default: `false`. |
| `lockscroll` | `boolean` | `true` | Locks document scroll when open. Default: `true`. |
| `ariaLabel` | `string` | `""` | Accessible name when slotted content has no visible title. Default: `""`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open` | `void` | When the overlay begins opening. |
| `vu-afteropen` | `void` | After the open transition window. |
| `vu-close` | `VuOverlayCloseDetail` | Cancelable close intent; parent sets `open` false when not prevented. |
| `vu-afterclose` | `void` | After the close transition window. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Centered content above the backdrop (e.g. a `vu-card` panel). |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Sets `open` to true. |
| `hide` | - Sets `open` to false. |
| `toggle` | - Toggles `open`. |
| `focus` | - Focuses the content frame. |

## CSS parts

| Name | Description |
| --- | --- |
| `backdrop` | Full-area scrim behind slotted content. |
| `content` | Flex centering frame for the default slot. |

## Types

### `VuOverlayCloseDetail`

```ts
{ reason: VuOverlayCloseReason; }
```

## Links

- Docs: https://velkinui.com/component/overlay
- Markdown: https://velkinui.com/component/overlay.md

---

# Popover

A popover component with smart placement and a trigger slot.

- **Tag:** `vu-popover`
- **Slug:** `popover`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuPopover` from `@velkin/react/popover`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuPopover } from "@velkin/react/popover";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the popover is open. |
| `anchor` | `VuPopoverAnchor` | — | Anchor selector, element, or ref object. |
| `anchorScope` | `VuPopoverAnchorScope` | `"document"` | `document` or shadow `root` lookup for selectors. |
| `anchorEl` | `HTMLElement \| null` | — | Direct anchor element (JS only). |
| `placement` | `VuPopoverPlacement` | `"auto"` | Preferred placement before flip. |
| `align` | `VuPopoverAlign` | `"start"` | Alignment along the anchor edge. |
| `gap` | `number` | `6` | Gap between anchor and surface in px. |
| `padding` | `number` | `8` | Viewport edge inset for flip/clamp math in px. |
| `matchAnchorWidth` | `boolean` | `false` | Matches surface width to the anchor. |
| `maxWidthToViewport` | `boolean` | `true` | Caps surface width to the viewport. |
| `maxWidthMode` | `VuPopoverMaxWidthMode` | `"cap"` | Max-width application strategy. |
| `flip` | `boolean` | `true` | Enables placement flipping. |
| `flipOrder` | `VuPopoverFlipSide[]` | `[]` | Preferred flip order. |
| `preset` | `VuPopoverPreset` | `"scale"` | Open/close animation preset. |
| `duration` | `number` | `220` | Open animation duration in ms. |
| `closeDuration` | `number` | `180` | Close animation duration in ms. |
| `animateReposition` | `boolean` | `true` | Animates position updates while open. |
| `repositionMs` | `number` | `160` | Reposition animation duration in ms. |
| `closeOnEscape` | `boolean` | `true` | Closes on Escape. |
| `closeOnOutside` | `boolean` | `true` | Closes on outside pointer down. |
| `restoreFocusOnClose` | `boolean` | `true` | Restores focus to the prior active element. |
| `ignoreOutsideSelector` | `string` | `""` | Selector for elements that ignore outside dismiss. |
| `ignoreOutsideAttr` | `string` | `"data-popover-ignore-outside"` | Attribute marking ignore zones for outside dismiss. |
| `groupEventName` | `string` | — | Optional coordinated group event channel. |
| `groupId` | `unknown` | — | Optional group identifier for coordinated open/close. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open` | `void` | When the popover begins opening. |
| `vu-close` | `void` | When the popover begins closing. |
| `vu-open-change` | `VuPopoverOpenChangeDetail` | When `open` changes. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Popover body (light DOM for host styling compatibility). |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Sets `open` to true. |
| `hide` | - Sets `open` to false. |
| `toggle` | - Toggles `open`. |
| `reconnectTarget` | - Re-resolves the anchor and syncs controller state. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Host is the positioned `popover="manual"` surface. |

## Types

### `HTMLElement | null`

```ts
null | HTMLElement
```

### `VuPopoverAlign`

```ts
"start" | "center" | "end"
```

### `VuPopoverAnchor`

```ts
undefined | null | string | HTMLElement | { value?: HTMLElement | null; }
```

### `VuPopoverAnchorScope`

```ts
"document" | "root"
```

### `VuPopoverMaxWidthMode`

```ts
"fill" | "cap"
```

### `VuPopoverOpenChangeDetail`

```ts
{ open: boolean; reason: CloseReason; }
```

### `VuPopoverPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuPopoverPreset`

```ts
"soft" | "none" | "fade" | "scale" | "slide" | "iosMenu" | "iosSheet" | "materialMenu" | "materialSheet" | "floaty" | "sharp" | "blurIn" | "blurFade" | "zoomFromAnchor" | "zoomFromCorner" | "flip3d" | "card3d" | "tilt3d" | "depth3d" | "rotate3d" | "springy" | "bouncy" | "glide" | "pop" | "drop" | "grow"
```

## Links

- Docs: https://velkinui.com/component/popover
- Markdown: https://velkinui.com/component/popover.md

---

# Progress

A progress component with linear, ring, and indeterminate modes.

- **Tag:** `vu-progress`
- **Slug:** `progress`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuProgress` from `@velkin/react/progress`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuProgress } from "@velkin/react/progress";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuProgressVariant` | `"default"` | Linear rail style or ring mode. Default: `"default"`. |
| `value` | `number` | `0` | Determinate fill from 0 to max. Default: `0`. |
| `max` | `number` | `100` | Maximum value for normalization. Default: `100`. |
| `buffer` | `number` | `0` | Buffered amount behind the fill. Default: `0`. |
| `indeterminate` | `boolean` | `false` | Animated unknown-progress mode. Default: `false`. |
| `size` | `VuProgressSize` | `"md"` | Track thickness preset. Default: `"md"`. |
| `tone` | `VuProgressTone` | `"normal"` | Neutral rail weight behind the fill. Default: `"normal"`. |
| `block` | `boolean` | `false` | Stretches to the container width. Default: `false`. |
| `color` | `VuProgressColor` | `"primary"` | Foreground fill intent token. Default: `"primary"`. |
| `speed` | `string` | `"1s"` | Indeterminate animation duration. Default: `"1s"`. |
| `label` | `string` | `""` | Accessible name; empty uses locale catalog. Default: `""`. |

## CSS parts

| Name | Description |
| --- | --- |
| `container` | Outer track shell or ring frame. |
| `bar` | Foreground fill in determinate mode. |
| `buffer` | Buffered segment behind the fill. |
| `indeterminate` | Animated segment in indeterminate mode. |
| `track` | Ring track stroke (`variant="ring"` only). |

## Types

### `VuProgressColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuProgressSize`

```ts
"sm" | "md" | "lg"
```

### `VuProgressTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuProgressVariant`

```ts
"outline" | "default" | "underline" | "ring"
```

## Links

- Docs: https://velkinui.com/component/progress
- Markdown: https://velkinui.com/component/progress.md

---

# Skeleton

A skeleton component with shimmer placeholders for loading layouts.

- **Tag:** `vu-skeleton`
- **Slug:** `skeleton`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuSkeleton` from `@velkin/react/skeleton`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSkeleton } from "@velkin/react/skeleton";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuSkeletonVariant` | `"rectangular"` | Shape hint (`text`, `circular`, `rectangular`). |
| `width` | `string` | `""` | CSS width; blank uses the variant default. |
| `height` | `string` | `""` | CSS height; blank uses the variant default. |
| `radius` | `string` | `""` | Corner preset or length; ignored for `circular`. |
| `animation` | `VuSkeletonAnimation` | `"wave"` | `wave`, `pulse`, or `none`. |
| `tone` | `VuSkeletonTone` | `"normal"` | Neutral surface weight behind the shimmer. |
| `inline` | `boolean` | `false` | Inline-block text-line layout. |

## CSS parts

| Name | Description |
| --- | --- |
| `root` | Shimmer block; wave overlay is `::after`. |

## Types

### `VuSkeletonAnimation`

```ts
"none" | "wave" | "pulse"
```

### `VuSkeletonTone`

```ts
"subtle" | "normal"
```

### `VuSkeletonVariant`

```ts
"text" | "circular" | "rectangular"
```

## Links

- Docs: https://velkinui.com/component/skeleton
- Markdown: https://velkinui.com/component/skeleton.md

---

# Spinner

A spinner component with multiple visual variants and overlay modes.

- **Tag:** `vu-spinner`
- **Slug:** `spinner`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuSpinner` from `@velkin/react/spinner`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSpinner } from "@velkin/react/spinner";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuSpinnerVariant` | `"solid"` | Spinner visual style. |
| `size` | `VuSpinnerSizePreset \| string` | `"md"` | Size preset or CSS length. |
| `color` | `VuSpinnerColor` | `"primary"` | Foreground intent token (`currentColor`). |
| `label` | `string` | `""` | Accessible name; defaults to a localized loading label. |
| `overlay` | `boolean` | `false` | Covers the parent element as an overlay. |
| `fullscreen` | `boolean` | `false` | Covers the viewport as a fullscreen overlay. |
| `backdropBlur` | `boolean` | `false` | Blurs content behind overlay modes. |
| `speed` | `number` | `1` | Animation speed multiplier (`1` = default rate). |
| `paused` | `boolean` | `false` | Pauses animation without removing the element. |

## CSS parts

| Name | Description |
| --- | --- |
| `spinner` | Root flex container; becomes the overlay surface when `overlay` / `fullscreen`. |
| `circle` | Ring-style variants (`solid`, `track`, `gradient`, …). |
| `dots` | Three-dot variant container. |
| `dot` | Individual dot in the `dots` variant. |
| `bars` | Four-bar variant container. |
| `bar` | Individual bar in the `bars` variant. |

## Types

### `VuSpinnerColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuSpinnerSizePreset | string`

```ts
string
```

### `VuSpinnerVariant`

```ts
"solid" | "gradient" | "dots" | "pulse" | "track" | "dashed" | "segment" | "dual" | "material" | "bars"
```

## Links

- Docs: https://velkinui.com/component/spinner
- Markdown: https://velkinui.com/component/spinner.md

---

# Tooltip

A tooltip component with smart placement and hover or click triggers.

- **Tag:** `vu-tooltip`
- **Slug:** `tooltip`
- **Category:** Feedback
- **Tier:** MIT
- **React:** `VuTooltip` from `@velkin/react/tooltip`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuTooltip } from "@velkin/react/tooltip";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the tooltip is visible. |
| `placement` | `VuTooltipPlacement` | `"top"` | Preferred side before collision flip. |
| `align` | `VuTooltipAlign` | `"center"` | Alignment along the trigger edge. |
| `trigger` | `VuTooltipTrigger` | `"hover"` | `hover`, `click`, or `both`. |
| `label` | `string` | `""` | Plain-text fallback when the `tooltip` slot is empty. |
| `variant` | `VuTooltipVariant` | `"elevated"` | Floating surface recipe (`elevated`, `outline`, `soft`). |
| `tone` | `VuTooltipTone` | `"normal"` | Neutral overlay weight. |
| `size` | `VuTooltipSize` | `"md"` | Padding and type scale. |
| `radius` | `VuTooltipRadius` | `"md"` | Corner preset (`sm`/`md`/`lg`; Role C′ omits `none`/`full`). |
| `arrow` | `boolean` | `false` | Draws a placement arrow on the bubble. |
| `interactive` | `boolean` | `false` | Allows pointer interaction with tooltip content. |
| `noAutoTrigger` | `boolean` | `false` | Disables hover/click/focus auto triggers; use methods only. |
| `delay` | `number` | — | Hover/focus dwell time (ms) before open; omit for `--vu-tooltip-delay` (1500ms). |
| `closeDelay` | `number` | — | Ms after pointer/focus leaves before close; omit for `--vu-tooltip-close-delay`. |
| `offset` | `number` | `6` | Gap between trigger and bubble in px. |
| `block` | `boolean` | `false` | Stretches the trigger to the container width. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open` | `void` | When the tooltip begins opening. |
| `vu-close` | `void` | When the tooltip begins closing. |
| `vu-open-change` | `VuTooltipOpenChangeDetail` | When `open` changes (including via methods). |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Trigger content (button, icon, text). |
| `tooltip` | Tooltip body; when empty, the `label` prop is shown. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Sets `open` to true. |
| `hide` | - Sets `open` to false (immediate; ignores `closeDelay`). |
| `toggle` | - Toggles `open`. |

## CSS parts

| Name | Description |
| --- | --- |
| `trigger` | Wrapper around the default slot. |
| `surface` | Positioned popover shell (`popover="manual"`). |
| `content` | Bubble surface with padding and optional arrow. |

## Types

### `VuTooltipAlign`

```ts
"start" | "center" | "end"
```

### `VuTooltipOpenChangeDetail`

```ts
{ open: boolean; }
```

### `VuTooltipPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuTooltipRadius`

```ts
"sm" | "md" | "lg"
```

### `VuTooltipSize`

```ts
"sm" | "md" | "lg"
```

### `VuTooltipTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuTooltipTrigger`

```ts
"both" | "click" | "hover"
```

### `VuTooltipVariant`

```ts
"outline" | "elevated" | "soft"
```

## Links

- Docs: https://velkinui.com/component/tooltip
- Markdown: https://velkinui.com/component/tooltip.md

---

# Tutorial

A tutorial component with spotlight overlays and guided popovers.

- **Tag:** `vu-tutorial`
- **Slug:** `tutorial`
- **Category:** Feedback
- **Tier:** Pro
- **React:** `VuTutorial` from `@velkin/react-pro/tutorial`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuTutorial } from "@velkin/react-pro/tutorial";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `TutorialStep[]` | `[]` | Tutorial steps; filtered with `step.when()` before running. |
| `open` | `boolean` | `false` | Whether the overlay is visible. |
| `startIndex` | `number` | `0` | Index used by `start()`. |
| `closeOnBackdrop` | `boolean` | `true` | Close when the dimmed mask is clicked (overridable per step). |
| `closeOnEscape` | `boolean` | `true` | Close on Escape. |
| `lockScroll` | `boolean` | `true` | Lock body scroll while open. |
| `spotlightPadding` | `number` | `0` | Extra padding around target rects. |
| `spotlightRadius` | `number` | `14` | Spotlight corner radius. |
| `popoverMaxWidth` | `number` | `380` | Max width of the tip panel. |
| `zIndex` | `number` | `9999` | Overlay z-index. |
| `progress` | `TutorialProgress` | `"counter"` | Progress indicator style. |
| `showGroup` | `boolean` | `true` | Show step group label. |
| `tourId` | `string` | `"default"` | Persistence key id. |
| `version` | `string` | `"v1"` | Persistence key version. |
| `persist` | `boolean` | `true` | Persist progress in localStorage. |
| `navigate` | `union` | — | SPA navigation for route steps. |
| `waitForRouteReady` | `() => void \| Promise<void>` | — | Await route readiness after navigate. |
| `labels` | `Partial` | `{}` | Override chrome labels. |
| `variant` | `VuTutorialVariant` | `"elevated"` | Floating tip surface recipe. Default: `"elevated"`. |
| `tone` | `VuTutorialTone` | `"normal"` | Neutral overlay weight. Default: `"normal"`. |
| `size` | `VuTutorialSize` | `"md"` | Tip panel size scale. Default: `"md"`. |
| `radius` | `VuTutorialRadius` | `"md"` | Tip panel corner radius. Default: `"md"`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open` | `VuTutorialEventDetail` | Tutorial opened. |
| `vu-step` | `VuTutorialEventDetail` | Step entered. |
| `vu-complete` | `VuTutorialEventDetail` | All steps completed. |
| `vu-skip` | `VuTutorialEventDetail` | Tour skipped. |
| `vu-close` | `VuTutorialEventDetail` | Tutorial closed. |
| `vu-missing` | `VuTutorialMissingTargetDetail` | Target could not be resolved. |
| `vu-noroute` | `VuTutorialRouteMissingNavigatorDetail` | Route step without navigate. |

## Slots

| Name | Description |
| --- | --- |
| `content:{stepId}` | Named slots for step-specific content (e.g. `content:first-step`). |

## Methods

| Name | Description |
| --- | --- |
| `start` | Opens from an index. |
| `next` | Advances one step. |
| `back` | Moves one step back. |
| `nextStep` | Alias for `next()`. |
| `prevStep` | Alias for `back()`. |
| `finish` | Completes and closes. |
| `skip` | Skips and closes. |
| `resume` | Resumes from persisted progress. |
| `reset` | Clears persisted state. |
| `isOpen` | Whether currently open. |
| `getCurrentStep` | Current step metadata. |
| `close` | Closes the overlay. |

## CSS parts

| Name | Description |
| --- | --- |
| `layer` | Full-viewport overlay layer. |
| `mask` | Dimmed SVG mask with spotlight holes. |
| `spotlight` | Highlighted target outline. |
| `connectors` | SVG connector layer. |
| `connector` | One connector path. |
| `annotation` | Floating annotation label. |
| `popover` | Tip panel (role=dialog). |
| `header` | Title/group row. |
| `body` | Step content region. |
| `footer` | Action button row. |

## Types

### `TutorialProgress`

```ts
"none" | "dots" | "bar" | "counter"
```

### `VuTutorialEventDetail`

```ts
{ tourId: string; version: string; index: number; total: number; stepId: string | null; group: string | null; }
```

### `VuTutorialMissingTargetDetail`

```ts
VuTutorialEventDetail & { target: string; }
```

### `VuTutorialRadius`

```ts
"sm" | "md" | "lg"
```

### `VuTutorialRouteMissingNavigatorDetail`

```ts
VuTutorialEventDetail & { route: string; }
```

### `VuTutorialSize`

```ts
"sm" | "md" | "lg"
```

### `VuTutorialTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuTutorialVariant`

```ts
"outline" | "elevated" | "soft"
```

## Links

- Docs: https://velkinui.com/component/tutorial
- Markdown: https://velkinui.com/component/tutorial.md

---

# Surfaces

# Accordion

An accordion component for expandable sections with keyboard navigation.

- **Tag:** `vu-accordion`
- **Slug:** `accordion`
- **Category:** Surfaces
- **Tier:** MIT
- **React:** `VuAccordion` from `@velkin/react/accordion`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAccordion } from "@velkin/react/accordion";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `true` | When false, at most one item may be open at a time. Default: `true`. |
| `collapsible` | `boolean` | `true` | With `multiple={false}`, allows closing the last open panel. Default: `true`. |
| `variant` | `VuAccordionVariant` | `"solid"` | Visual variant of the container. Default: `"solid"`. |
| `tone` | `VuAccordionTone` | `"normal"` | Neutral surface weight for `solid` / `splitted` fills. Default: `"normal"`. |
| `size` | `VuAccordionSize` | `"md"` | Header/body density (`sm` \\| `md` \\| `lg`). Default: `"md"`. |
| `disabled` | `boolean` | `false` | Disables interaction for all direct items. Default: `false`. |
| `flush` | `boolean` | `false` | Removes the dividing line between items in `light`, `solid`, and `outline` variants. Default: `false`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open-change` | `VuAccordionItemOpenChangeDetail` | Bubbles from items when their open state changes. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - One or more direct `<vu-accordion-item>` children. |

## Methods

| Name | Description |
| --- | --- |
| `expandAll` | Opens all items; in single mode opens only the first. |
| `collapseAll` | Closes all items (respects `collapsible` in single mode). |
| `openItem` | Opens an item by index; returns whether the operation succeeded. |
| `closeItem` | Closes an item by index; returns whether the operation succeeded. |
| `toggleItem` | Toggles an item by index; returns whether the operation succeeded. |
| `focusItem` | Moves focus to an item header by index. |

## CSS parts

| Name | Description |
| --- | --- |
| `group` | Wrapper that contains all slotted accordion items. |

## Types

### `VuAccordionItemOpenChangeDetail`

```ts
{ open: boolean; }
```

### `VuAccordionSize`

```ts
"sm" | "md" | "lg"
```

### `VuAccordionTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuAccordionVariant`

```ts
"light" | "solid" | "outline" | "split" | "splitted"
```

## Links

- Docs: https://velkinui.com/component/accordion
- Markdown: https://velkinui.com/component/accordion.md

---

# Accordion Item

A collapsible accordion item component with a header trigger and body panel.

- **Tag:** `vu-accordion-item`
- **Slug:** `accordion-item`
- **Category:** Surfaces
- **Tier:** MIT
- **React:** `VuAccordionItem` from `@velkin/react/accordion-item`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAccordionItem } from "@velkin/react/accordion-item";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the item is expanded. Default: `false`. |
| `disabled` | `boolean` | `false` | Prevents interaction. Default: `false`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open-change` | `VuAccordionItemOpenChangeDetail` | After open state changes. |

## Slots

| Name | Description |
| --- | --- |
| `start` | Leading visual before the title group. |
| `title` | Primary header content. |
| `sub-title` | Secondary header content. |
| `expand-icon` | Trailing control while collapsed. |
| `collapse-icon` | Trailing control while expanded. |
| `body` | Collapsible body content. |

## Methods

| Name | Description |
| --- | --- |
| `expand` | - Expands and emits `vu-open-change` when state changes. |
| `collapse` | - Collapses and emits `vu-open-change` when state changes. |
| `toggle` | - Toggles open state and emits `vu-open-change`. |

## CSS parts

| Name | Description |
| --- | --- |
| `item` | Item root wrapper. |
| `header` | Interactive header trigger. |
| `start` | Leading visual wrapper. |
| `title` | Primary title wrapper. |
| `sub-title` | Secondary title wrapper. |
| `icon` | Expand or collapse icon wrapper. |
| `body` | Collapsible body container. |

## Types

### `VuAccordionItemOpenChangeDetail`

```ts
{ open: boolean; }
```

## Links

- Docs: https://velkinui.com/component/accordion-item
- Markdown: https://velkinui.com/component/accordion-item.md

---

# Card

A card component with media, header, body, and footer slots.

- **Tag:** `vu-card`
- **Slug:** `card`
- **Category:** Surfaces
- **Tier:** MIT
- **React:** `VuCard` from `@velkin/react/card`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCard } from "@velkin/react/card";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuCardVariant` | `"elevated"` | Surface paint recipe. Default: `"elevated"`. |
| `tone` | `VuCardTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuCardSize` | `"md"` | Content shell padding and section gap. Default: `"md"`. |
| `radius` | `VuCardRadius` | `"md"` | Corner radius preset. Default: `"md"`. |
| `orientation` | `VuCardOrientation` | `"vertical"` | Layout axis. Default: `"vertical"`. |
| `divider` | `VuCardDivider` | `"none"` | Section hairline strategy. Default: `"none"`. |
| `flush` | `boolean` | `false` | Zeros content shell padding. Default: `false`. |
| `interactive` | `boolean` | `false` | Focusable surface that dispatches `vu-activate`. Default: `false`. |
| `selected` | `boolean` | `false` | Chosen-state ring; sets `aria-pressed` when `interactive`. Default: `false`. |
| `disabled` | `boolean` | `false` | Blocks interaction when `interactive`. Default: `false`. |
| `label` | `string` | `""` | Accessible name when `interactive` and no visible heading. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-activate` | `VuCardActivateDetail` | Fires on click or keyboard activation (Enter / Space) when `interactive` and not `disabled`. Detail: `{ source }` where `source` is the original `MouseEvent` / `KeyboardEvent`. |

## Slots

| Name | Description |
| --- | --- |
| `media` | Full-bleed media (image, video, picture, svg). No padding; auto-sizes common media tags to `inline-size: 100%`. In `orientation="horizontal"`, this slot sits on the start edge instead of on top. |
| `media-actions` | Overlay actions positioned at the top-end of `media` (favorite, play, options menu). `media` is the containing block, so any slotted element is absolutely positioned for free — typically icon buttons. |
| `header` | Top section. Renders as a flex row with `space-between` (title left, secondary action right) so a slotted heading + actions split naturally; wraps on narrow widths. |
| `—` | - Body content (the default slot). |
| `footer` | Bottom section. Renders as a flex row with `flex-end` (actions on the trailing edge — `Cancel` + `Save` pattern). For status-text + action layouts, add `margin-inline-start: auto` to the trailing item. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | The outer surface that lays the variant paint. |
| `media` | The media wrapper around the `media` slot. Acts as the positioning context for `media-actions`. |
| `media-actions` | The overlay wrapper around the `media-actions` slot. Top-end of `media` by default. |
| `media-divider` | Hairline between media and content when `divider` is `header` or `all`. |
| `content` | Column wrapping `header` / body / `footer`; holds the shared padding inset and vertical `gap` between sections. |
| `header` | The header section. |
| `section-divider` | Hairline between adjacent content sections when `divider` is set. |
| `body` | The body section. |
| `footer` | The footer section. |

## Types

### `VuCardActivateDetail`

```ts
{ source: Event; }
```

### `VuCardDivider`

```ts
"none" | "header" | "footer" | "all"
```

### `VuCardOrientation`

```ts
"horizontal" | "vertical"
```

### `VuCardRadius`

```ts
"sm" | "md" | "lg"
```

### `VuCardSize`

```ts
"sm" | "md" | "lg"
```

### `VuCardTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuCardVariant`

```ts
"outline" | "elevated" | "soft" | "ghost" | "filled" | "glass" | "gradient"
```

## Links

- Docs: https://velkinui.com/component/card
- Markdown: https://velkinui.com/component/card.md

---

# Carousel

A slide carousel component with navigation, drag, and autoplay.

- **Tag:** `vu-carousel`
- **Slug:** `carousel`
- **Category:** Surfaces
- **Tier:** MIT
- **React:** `VuCarousel` from `@velkin/react/carousel`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCarousel } from "@velkin/react/carousel";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` | `0` | Active slide index (zero-based). Reflected so consumers can drive it from outside via `index` attribute. |
| `slidesPerView` | `number` | `1` | How many slides are visible at once. |
| `slidesToScroll` | `number` | `1` | How many slides advance per `next()` / `prev()` / dot click. |
| `loop` | `boolean` | `false` | Wraps around at the end / start instead of stopping. When `false` (default), navigation stops at the edges and arrow buttons get `disabled`. |
| `autoplay` | `boolean` | `false` | Auto-rotates through slides. Off by default — auto-rotation is hostile UX without an explicit ask. Respects `prefers-reduced-motion: reduce` (treated as off). |
| `interval` | `number` | `5000` | Milliseconds between autoplay advances. |
| `pauseOnHover` | `boolean` | `true` | Pause autoplay while the pointer is over the carousel. Focus-within always pauses regardless of this flag (a11y requirement). |
| `controls` | `VuCarouselControls` | `"dots"` | Which navigation affordances render. |
| `gap` | `VuCarouselGap` | `"none"` | Gap between slides. |
| `orientation` | `VuCarouselOrientation` | `"horizontal"` | Layout axis. `vertical` requires a host `block-size` so the viewport has something to clip against. |
| `label` | `string` | `""` | Accessible name for the carousel — required by the WAI-ARIA carousel pattern (the screen reader needs to know the *purpose* of the carousel). |
| `prevLabel` | `string` | `""` | Previous control name; empty uses the locale catalog. |
| `nextLabel` | `string` | `""` | Next control name; empty uses the locale catalog. |
| `dotsLabel` | `string` | `""` | Dot tablist name; empty uses the locale catalog. |
| `loading` | `boolean` | `false` | Show a loading overlay (spinner + dimmed surface) and mark the host `aria-busy`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuCarouselChangeDetail` | Active slide index changed (API, click, drag, keyboard, or autoplay).

Composition: slot `<vu-carousel-item>` children as slides. The component handles layout (flex track + per-slide flex-basis), translation (CSS `transform` driven by `--carousel-index`), drag (pointer events with capture, snaps on threshold), autoplay (auto-pauses on hover, focus-within, when offscreen, when reduced-motion is set), and ARIA (region/slide labels, live region, dot tablist semantics).

Layout: `slidesPerView` and `gap` together determine each slide's flex-basis: `(100% - (slidesPerView - 1) * gap) / slidesPerView`. The track translates by `index * (basis + gap)` — one transform handles every (slides, gap, direction) combination. Vertical orientation flips the axis; consumers must give the host a `block-size` so there's a viewport to clip against. `<vu-carousel-item>` fills each vertical slice automatically.

Accessibility (per WAI-ARIA APG carousel pattern): host carries `role="region"` and `aria-roledescription="carousel"`; pass `label` to set the accessible name (e.g., "Featured products"). Each `<vu-carousel-item>` gets `role="group"`, `aria-roledescription="slide"`, `aria-label` from item `label` or "N of M", and `inert` + `aria-hidden` when offscreen. Dots are real `<button>` elements with `aria-current="true"` on the active one. A visually-hidden live region (`aria-live="polite"`) announces the current slide on change. Keyboard: ArrowLeft / ArrowRight (or ArrowUp / ArrowDown for vertical) move; Home / End jump to first / last. Autoplay pauses on hover, focus-within, when the carousel scrolls offscreen, and when `prefers-reduced-motion: reduce` is set. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Default slot for `<vu-carousel-item>` slides. The parent relays slide ARIA (`role="group"`, roledescription, "N of M" / item `label`, `inert` / `aria-hidden` when offscreen). |
| `prev-icon` | Optional override for the previous-arrow icon. Defaults to a chevron. |
| `next-icon` | Optional override for the next-arrow icon. Defaults to a chevron. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Outer wrapper containing viewport and controls. |
| `viewport` | The clipping container; slides translate within this. |
| `track` | The flex container that translates by `--carousel-index`. |
| `prev` | The previous-slide button. |
| `next` | The next-slide button. |
| `dots` | The container for dot indicators. |
| `dot` | Each dot indicator (a real `<button>`). |
| `dot-active` | Added to the active dot (for `::part(dot-active)` styling). |
| `live` | The visually-hidden live region announcing the current slide. |
| `loading` | The loading overlay shown when `loading` is true. |
| `spinner` | The spinner inside the loading overlay. |

## Types

### `VuCarouselChangeDetail`

```ts
{ index: number; previous: number; }
```

### `VuCarouselControls`

```ts
"none" | "arrows" | "dots" | "both"
```

### `VuCarouselGap`

```ts
"sm" | "md" | "lg" | "none"
```

### `VuCarouselOrientation`

```ts
"horizontal" | "vertical"
```

## Links

- Docs: https://velkinui.com/component/carousel
- Markdown: https://velkinui.com/component/carousel.md

---

# Carousel Item

A carousel slide component for use inside `<vu-carousel>`.

- **Tag:** `vu-carousel-item`
- **Slug:** `carousel-item`
- **Category:** Surfaces
- **Tier:** MIT
- **React:** `VuCarouselItem` from `@velkin/react/carousel-item`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuCarouselItem } from "@velkin/react/carousel-item";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `""` | Optional accessible name for this slide; when empty the parent supplies "N of M". |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Slide content (media, cards, or any markup). |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Slide content wrapper.

Always slot inside `<vu-carousel>`. The parent relays slide position, visibility, orientation, and localized role text via internal properties — do not set those yourself. |

## Links

- Docs: https://velkinui.com/component/carousel-item
- Markdown: https://velkinui.com/component/carousel-item.md

---

# Navigation

# Adaptive Bar

A responsive toolbar component that overflows extra items into a menu.

- **Tag:** `vu-adaptive-bar`
- **Slug:** `adaptive-bar`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuAdaptiveBar` from `@velkin/react/adaptive-bar`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAdaptiveBar } from "@velkin/react/adaptive-bar";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuAdaptiveBarVariant` | `"flat"` | Bar surface treatment. Default: `"flat"`. |
| `tone` | `VuAdaptiveBarTone` | `"normal"` | Neutral bar surface weight. Default: `"normal"`. |
| `size` | `VuAdaptiveBarSize` | `"md"` | Bar padding, gap, and minimum height. Default: `"md"`. |
| `justify` | `VuAdaptiveBarJustify` | `"start"` | Inline alignment of visible items. Default: `"start"`. |
| `itemSize` | `VuAdaptiveItemSize` | `"md"` | Size forwarded to `<vu-adaptive-item>` children without their own `size`. Default: `"md"`. |
| `menuOpen` | `boolean` | `false` | Whether the overflow menu is open. |
| `fullyOverflowed` | `boolean` | — | Read-only — true when every item is in the overflow menu. |
| `gapThreshold` | `number` | `0` | Extra px buffer subtracted during measurement (padding/gaps are computed automatically). Default: `0`. |
| `moreLabel` | `string` | `"More"` | Accessible name for the overflow trigger. Default: `"More"`. |
| `placement` | `VuAdaptiveBarPlacement` | `"bottom"` | Preferred overflow popover side. Default: `"bottom"`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open-change` | `VuAdaptiveBarOpenChangeDetail` | Fired when the overflow menu opens or closes. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Default slot for bar items. Use `<vu-adaptive-item>` or any element with `data-adaptive-item`. |
| `overflow` | Receives items that no longer fit in the main bar (assigned automatically). |

## Methods

| Name | Description |
| --- | --- |
| `openMenu` | Opens the overflow menu. |
| `closeMenu` | Closes the overflow menu. |
| `toggleMenu` | Toggles the overflow menu state. |
| `recalculateLayout` | Re-runs layout and overflow measurement. |

## CSS parts

| Name | Description |
| --- | --- |
| `bar` | Outer paint surface (background, border, shadow). |
| `container` | Inner flex row (padding, gap, item alignment). |
| `items` | Visible-item list wrapper (`role="list"`). |
| `overflow-button` | The overflow toggle button. |
| `menu` | The dropdown menu container. |
| `menu-inner` | Wrapper inside the dropdown menu. |

## Types

### `VuAdaptiveBarJustify`

```ts
"start" | "center" | "end"
```

### `VuAdaptiveBarOpenChangeDetail`

```ts
{ open: boolean; }
```

### `VuAdaptiveBarPlacement`

```ts
"top" | "bottom" | "left" | "right"
```

### `VuAdaptiveBarSize`

```ts
"sm" | "md" | "lg"
```

### `VuAdaptiveBarTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuAdaptiveBarVariant`

```ts
"outline" | "flat" | "elevated"
```

### `VuAdaptiveItemSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/adaptive-bar
- Markdown: https://velkinui.com/component/adaptive-bar.md

---

# Appbar

An application bar component with start, center, and end slots.

- **Tag:** `vu-appbar`
- **Slug:** `appbar`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuAppbar` from `@velkin/react/appbar`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuAppbar } from "@velkin/react/appbar";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `VuAppbarVariant` | `"flat"` | Surface paint recipe. Default: `"flat"`. |
| `tone` | `VuAppbarTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuAppbarSize` | `"md"` | Padding, gap, and bar height. Default: `"md"`. |
| `placement` | `VuAppbarPlacement` | `"top"` | Pin to top or bottom when `sticky`. Default: `"top"`. |
| `sticky` | `boolean` | `false` | Pins via `position: sticky`. Default: `false`. |
| `condense` | `boolean` | `false` | Elevates the bar after scroll when `sticky`. Default: `false`. |
| `autohide` | `boolean` | `false` | Hides on scroll-down, reveals on scroll-up. Default: `false`. |

## Slots

| Name | Description |
| --- | --- |
| `start` | Leading content; hidden when empty. |
| `—` | - Center content; hidden when empty. |
| `end` | Trailing content; hidden when empty. |

## CSS parts

| Name | Description |
| --- | --- |
| `bar` | Outer paint surface. |
| `container` | Inner layout row. |
| `start` | Leading slot wrapper. |
| `body` | Center slot wrapper. |
| `end` | Trailing slot wrapper. |

## Types

### `VuAppbarPlacement`

```ts
"top" | "bottom"
```

### `VuAppbarSize`

```ts
"sm" | "md" | "lg"
```

### `VuAppbarTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuAppbarVariant`

```ts
"outline" | "flat" | "elevated"
```

## Links

- Docs: https://velkinui.com/component/appbar
- Markdown: https://velkinui.com/component/appbar.md

---

# Breadcrumb

A breadcrumb component for navigation trails with optional collapse.

- **Tag:** `vu-breadcrumb`
- **Slug:** `breadcrumb`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuBreadcrumb` from `@velkin/react/breadcrumb`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuBreadcrumb } from "@velkin/react/breadcrumb";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `separator` | `string` | `"/"` | Glyph between items; forwarded via `--breadcrumb-separator`. Default: `"/"`. |
| `size` | `VuBreadcrumbSize` | `"md"` | Typography scale forwarded to children. Default: `"md"`. |
| `max` | `number` | `0` | Collapse threshold; `0` never collapses by count. Default: `0`. |
| `itemsBefore` | `number` | `1` | Leading items kept when collapsed; HTML attribute is `itemsbefore`. Default: `1`. |
| `itemsAfter` | `number` | `1` | Trailing items kept when collapsed; HTML attribute is `itemsafter`. Default: `1`. |
| `responsive` | `boolean` | `false` | Auto-collapse when the trail no longer fits. Default: `false`. |
| `overflow` | `VuBreadcrumbOverflow` | `"menu"` | Hidden-segment UI (`menu` \| `inline`). Default: `"menu"`. |
| `expanded` | `boolean` | `false` | Suspends collapse and reveals every item. Default: `false`. |
| `showExpandAction` | `boolean` | `true` | Footer action to reveal the full trail when `overflow="menu"`. Default: `true`. |
| `expandActionLabel` | `string` | `""` | Footer action label; empty uses the locale catalog. |
| `disabled` | `boolean` | `false` | Dims the trail and disables pointer events. Default: `false`. |
| `label` | `string` | `""` | Accessible name for the wrapping `<nav>`. Default: `"Breadcrumb"`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-reveal` | `VuBreadcrumbRevealDetail` | Fired when the full trail is revealed (`overflow="inline"` ellipsis click, or "Show full trail" in the menu). |

## Slots

| Name | Description |
| --- | --- |
| `—` | - One or more `<vu-breadcrumb-item>` children, in hierarchy order (root → leaf). |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | The `<nav>` wrapper. |
| `list` | The `role="list"` container holding items + ellipsis. |
| `ellipsis` | The `<li>` housing the overflow trigger; only present while collapsed. |
| `ellipsis-separator` | The leading separator inside the ellipsis tile. |
| `ellipsis-button` | The clickable button that opens the overflow menu or expands inline. |
| `overflow-menu` | The popover panel listing hidden segments (`overflow="menu"` only). |
| `overflow-item` | Each row button inside the overflow menu. |
| `overflow-divider` | Separator before the optional expand footer. |
| `overflow-expand` | Footer button that sets `expanded` to show the full trail. |

## Types

### `VuBreadcrumbOverflow`

```ts
"menu" | "inline"
```

### `VuBreadcrumbSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/breadcrumb
- Markdown: https://velkinui.com/component/breadcrumb.md

---

# Context Menu

A context menu component with grouped actions and icons.

- **Tag:** `vu-context-menu`
- **Slug:** `context-menu`
- **Category:** Navigation
- **Tier:** Pro
- **React:** `VuContextMenu` from `@velkin/react-pro/context-menu`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuContextMenu } from "@velkin/react-pro/context-menu";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `VuContextMenuItem[]` | `[]` | Menu entries with optional icons, grouping, and target filtering. |
| `context` | `VuContextMenuContext \| null` | `null` | Active pointer context from `openAt` or a host such as `<vu-flow>`. |
| `overlay` | `boolean` | `false` | When true, renders a viewport overlay positioned at `context.clientX/Y`. Default: `false` for `<vu-flow>` slot usage. |
| `open` | `boolean` | `false` | Reflected open state when visible rows or slotted content are shown. |
| `variant` | `VuContextMenuVariant` | `"elevated"` | Panel surface recipe (`elevated`/`outline`/`soft`). Default: `"elevated"`. |
| `tone` | `VuContextMenuTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuContextMenuSize` | `"md"` | Row density (`sm`, `md`, `lg`). Default: `md`. |
| `radius` | `VuContextMenuRadius` | `"md"` | Panel corner preset (`sm`/`md`/`lg`). Default: `"md"`. |
| `label` | `string` | `""` | Accessible name for the menu panel; localized default when empty. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-activate` | `VuContextMenuItemClickDetail` | When a menu row is activated. |
| `vu-open` | `void` | When the menu becomes visible. |
| `vu-close` | `void` | When the menu hides. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Optional custom menu content when not using `items`. |

## Methods

| Name | Description |
| --- | --- |
| `hasVisibleItems` | Returns true when at least one row is visible for the active `context`. |
| `openAt` | Opens the menu at viewport coordinates. |
| `close` | Clears `context` and hides the menu. |

## CSS parts

| Name | Description |
| --- | --- |
| `backdrop` | Full-screen dismiss layer in `overlay` mode. |
| `panel` | Menu surface (`role="menu"`). |
| `submenu` | Nested flyout panel for rows with `children`. |
| `item` | Action row button. |
| `item-label` | Visible label text inside a row. |
| `divider` | Horizontal separator between rows or groups. |
| `group-label` | Uppercase section label above a group. |

## Types

### `VuContextMenuContext | null`

```ts
null | { target: VuContextMenuTarget; clientX: number; clientY: number; graphX?: number; graphY?: number; node?: unknown; edge?: unknown; nodes?: unknown[]; edges?: unknown[]; value?: string; data?: unknown; }
```

### `VuContextMenuItemClickDetail`

```ts
{ item: VuContextMenuItem; context: VuContextMenuContext; }
```

### `VuContextMenuRadius`

```ts
"sm" | "md" | "lg"
```

### `VuContextMenuSize`

```ts
"sm" | "md" | "lg"
```

### `VuContextMenuTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuContextMenuVariant`

```ts
"outline" | "elevated" | "soft"
```

## Links

- Docs: https://velkinui.com/component/context-menu
- Markdown: https://velkinui.com/component/context-menu.md

---

# Dropdown

A dropdown menu component with trigger slot and keyboard navigation.

- **Tag:** `vu-dropdown`
- **Slug:** `dropdown`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuDropdown` from `@velkin/react/dropdown`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuDropdown } from "@velkin/react/dropdown";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` | `VuDropdownTrigger` | `"click"` | Open interaction mode. Default: `"click"`. |
| `placement` | `VuDropdownPlacement` | `"bottom"` | Preferred side before collision flip. Default: `"bottom"`. |
| `align` | `VuDropdownAlign` | `"center"` | Alignment along the trigger edge. Default: `"center"`. |
| `open` | `boolean` | `false` | Whether the menu is visible. Default: `false`. |
| `value` | `string` | `""` | Last selected row token. Default: `""`. |
| `width` | `VuDropdownWidthPreset \| string` | `"auto"` | Panel inline size preset or CSS length. Default: `"auto"`. |
| `variant` | `VuDropdownVariant` | `"elevated"` | Panel surface paint recipe. Default: `"elevated"`. |
| `tone` | `VuDropdownTone` | `"normal"` | Neutral surface weight. Default: `"normal"`. |
| `size` | `VuDropdownSize` | `"md"` | Panel padding scale; forwards to items without their own. Default: `"md"`. |
| `itemColor` | `VuDropdownItemColor` | `"default"` | Row intent forwarded to items without their own. Default: `"default"`. |
| `radius` | `VuDropdownRadius` | `"md"` | Panel corner preset (`sm`/`md`/`lg`; Role C′ omits `none`/`full`). Default: `"md"`. |
| `maxHeight` | `string` | `""` | Max scroll region block size; empty uses stylesheet default. Default: `""`. |
| `closeOnSelect` | `boolean` | `true` | Close after a row activates. Default: `true`. |
| `offset` | `number` | `8` | Gap in px between trigger and panel. Default: `8`. |
| `disabled` | `boolean` | `false` | Blocks open and closes an open menu. Default: `false`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open-change` | `VuDropdownOpenChangeDetail` | When `open` changes (`detail.open`). |
| `vu-select` | `VuDropdownSelectDetail` | When a row is activated. |
| `vu-open` | `void` | When the menu begins opening. |
| `vu-close` | `void` | When the menu begins closing. |

## Slots

| Name | Description |
| --- | --- |
| `trigger` | Clickable or hoverable control (typically `<vu-button>`). |
| `—` | - Menu rows (`<vu-dropdown-item>`), `<vu-divider>`, or `role="menuitem"`. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Sets `open` to true. |
| `hide` | - Sets `open` to false. |
| `toggle` | - Toggles `open`. |
| `focus` | - Focuses the slotted trigger control. |

## CSS parts

| Name | Description |
| --- | --- |
| `trigger` | Wrapper around the trigger slot. |
| `body` | Positioned menu panel (`role="menu"`). |
| `body-scroll` | Scrollable inner wrapper when content exceeds max height. |

## Types

### `VuDropdownAlign`

```ts
"start" | "center" | "end"
```

### `VuDropdownItemColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuDropdownOpenChangeDetail`

```ts
{ open: boolean; }
```

### `VuDropdownPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuDropdownRadius`

```ts
"sm" | "md" | "lg"
```

### `VuDropdownSelectDetail`

```ts
{ value: string; label: string; item: HTMLElement; checked?: boolean; kind?: VuDropdownItemKind; href?: string; }
```

### `VuDropdownSize`

```ts
"sm" | "md" | "lg"
```

### `VuDropdownTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuDropdownTrigger`

```ts
"click" | "hover" | "submenu"
```

### `VuDropdownVariant`

```ts
"outline" | "elevated" | "soft"
```

### `VuDropdownWidthPreset | string`

```ts
string
```

## Links

- Docs: https://velkinui.com/component/dropdown
- Markdown: https://velkinui.com/component/dropdown.md

---

# Menubar

A menubar component with nested submenus and keyboard navigation.

- **Tag:** `vu-menubar`
- **Slug:** `menubar`
- **Category:** Navigation
- **Tier:** Pro
- **React:** `VuMenubar` from `@velkin/react-pro/menubar`

## Import

```bash
npm i @velkin/react-pro
```

```tsx
import { VuMenubar } from "@velkin/react-pro/menubar";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `VuMenubarItem[]` | `[]` | Menu item tree. |
| `disabled` | `boolean` | `false` | Disables the entire menubar. Default: `false`. |
| `pwaOverlay` | `boolean` | `false` | Window-controls-overlay placement (`pwaoverlay` attr). Default: `false`. |
| `size` | `VuMenubarSize` | `"md"` | Bar item padding and height. Default: `"md"`. |
| `tone` | `VuMenubarTone` | `"normal"` | Bar foreground weight. Default: `"normal"`. |
| `overflowThreshold` | `number` | `0` | Minimum visible items before overflow mode. Default: `0`. |
| `menuTrigger` | `VuMenubarMenuTrigger` | `"click"` | Desktop submenu open interaction (`menutrigger` attr). Default: `"click"`. |
| `variant` | `VuMenubarVariant` | `"flat"` | Bar surface paint recipe. Default: `"flat"`. |
| `indicator` | `VuMenubarIndicator` | `"underline"` | Active top-level affordance (`underline`/`pill`/`dot`/`none`); `pill` is selection chrome — not `radius="full"`. Default: `"underline"`. |
| `contained` | `boolean` | `false` | Centers the bar row with a max inline width. Default: `false`. |
| `justifyBar` | `string` | `"flex-start"` | CSS `justify-content` for the outer bar (`justifybar` attr). |
| `justifyBarItems` | `string` | `"flex-start"` | CSS `justify-content` for the item row (`justifybaritems` attr). |
| `placement` | `VuMenubarPlacement` | `"bottom"` | Preferred side for top flyout. Default: `"bottom"`. |
| `align` | `VuMenubarAlign` | `"start"` | Alignment along the trigger edge. Default: `"start"`. |
| `offset` | `number` | `4` | Gap in px between trigger and flyout. Default: `4`. |
| `breakpoint` | `number` | `768` | Mobile breakpoint in pixels. Default: `768`. |
| `isMobile` | `boolean` | `false` | Mobile layout flag (`ismobile` attr). |
| `sticky` | `boolean` | `false` | Pins to the top of the scroll container. Default: `false`. |
| `condense` | `boolean` | `false` | Elevates and shortens the bar when `sticky`. Default: `false`. |
| `menubarLabel` | `string` | `""` | Menubar landmark accessible name (`menubarlabel` attr). |
| `nestedSubmenuLabel` | `string` | `""` | Nested flyout accessible name (`nestedsubmenulabel` attr). |
| `menuLabel` | `string` | `""` | Mobile menu toggle accessible name (`menulabel` attr). |
| `drawerLabel` | `string` | `""` | Mobile drawer accessible name (`drawerlabel` attr). |
| `closeLabel` | `string` | `""` | Mobile drawer close accessible name (`closelabel` attr). |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-activate` | `VuMenubarActivateDetail` | When an item is activated. |
| `vu-check` | `VuMenubarCheckDetail` | When a checkbox item toggles. |
| `vu-select` | `VuMenubarSelectDetail` | When a radio item is selected. |

## Slots

| Name | Description |
| --- | --- |
| `prepend` | Content before menu items on desktop. |
| `append` | Content after menu items on desktop. |
| `prepend-mobile` | Content before navigation items in mobile mode. |
| `append-mobile` | Content after navigation items in mobile mode. |
| `header` | Header content for the mobile drawer. |
| `footer` | Footer content for the mobile drawer. |

## Methods

| Name | Description |
| --- | --- |
| `focusFirst` | - Focuses the first top-level menu item. |
| `focusLast` | - Focuses the last top-level menu item. |
| `closeMenus` | - Closes all open flyouts. |
| `openMenu` | - Opens the mobile drawer menu. |
| `closeMenu` | - Closes mobile drawer and desktop submenus. |
| `toggleMenu` | - Toggles the mobile drawer menu. |

## CSS parts

| Name | Description |
| --- | --- |
| `menu-bar` | Main menubar container. |
| `menubar-desktop` | Desktop menubar region. |
| `menubar-mobile` | Mobile chrome. |
| `menu-item` | Top-level menu item button. |
| `top-menu` | Top-level flyout panel. |
| `nested-menu` | Nested flyout panel. |
| `submenu-item` | Item within a submenu. |

## Types

### `VuMenubarActivateDetail`

```ts
{ item: VuMenubarItem; path: string; isSubmenu: boolean; value: unknown; }
```

### `VuMenubarAlign`

```ts
"start" | "center" | "end"
```

### `VuMenubarCheckDetail`

```ts
{ item: VuMenubarItem; path: string; checked: boolean; }
```

### `VuMenubarIndicator`

```ts
"none" | "dot" | "underline" | "pill"
```

### `VuMenubarMenuTrigger`

```ts
"auto" | "click" | "hover"
```

### `VuMenubarPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuMenubarSelectDetail`

```ts
{ path: string; group: string; }
```

### `VuMenubarSize`

```ts
"sm" | "md" | "lg"
```

### `VuMenubarTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuMenubarVariant`

```ts
"outline" | "flat" | "elevated"
```

## Links

- Docs: https://velkinui.com/component/menubar
- Markdown: https://velkinui.com/component/menubar.md

---

# Nav Panel

A navigation panel component for drawer bodies with icon-rail collapse.

- **Tag:** `vu-nav-panel`
- **Slug:** `nav-panel`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuNavPanel` from `@velkin/react/nav-panel`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuNavPanel } from "@velkin/react/nav-panel";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `VuNavPanelItem[]` | `[]` | Rows to render; shared `category` values create collapsible groups. |
| `value` | `string` | `""` | Currently selected row key. |
| `collapsedGroups` | `Record` | `{}` | Group collapsed-state map (`true` means collapsed). |
| `collapsed` | `boolean` | `false` | Icon-rail mode; labels and group headings are hidden. |
| `label` | `string` | `"Navigation"` | Accessible name for the listbox. |
| `size` | `VuNavPanelSize` | `"md"` | Row density (`sm`, `md`, `lg`); relayed to rail tooltips. |
| `color` | `VuNavPanelColor` | `"default"` | Active-row accent color. |
| `collapsedHints` | `VuNavPanelCollapsedHints` | `"tooltip"` | Icon-rail label reveal: per-row `vu-tooltip`, native `title`, or `none`. |
| `collapsedHintPlacement` | `VuNavPanelHintPlacement` | `"right"` | Hint side for rail rows when `collapsedHints="tooltip"`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuNavPanelChangeDetail` | When the selected row changes. |
| `vu-collapse-change` | `VuNavPanelCollapseChangeDetail` | When icon-rail `collapsed` flips. |

## Slots

| Name | Description |
| --- | --- |
| `prepend` | Content before rows inside the list body. |
| `append` | Content after rows inside the list body. |

## Methods

| Name | Description |
| --- | --- |
| `select` | - Sets the selected row by `value`. |
| `collapse` | - Collapses to the icon rail. |
| `expand` | - Expands from the icon rail. |
| `toggleCollapse` | - Toggles icon-rail mode. |
| `toggleGroup` | - Toggles or forces a group collapsed state. |
| `expandAllGroups` | - Expands all known groups. |
| `collapseAllGroups` | - Collapses all known groups. |

## CSS parts

| Name | Description |
| --- | --- |
| `panel` | Root list region. |
| `body` | Scrollable container for rows and groups. |
| `prepend` | Prepend slot wrapper. |
| `append` | Append slot wrapper. |
| `list` | Flat list container when items have no categories. |
| `group` | Wrapper for a category section. |
| `heading` | Clickable heading row of a category. |
| `chevron` | Chevron icon in the heading. |
| `group-content` | Container of rows inside a category. |
| `row` | A single selectable row (`button` or `a`). |
| `stack` | Label and description column inside a row. |
| `label` | Primary row text. |
| `description` | Secondary row text. |
| `badge` | Optional trailing meta on a row. |
| `icon` | Leading or trailing icon on a row. |
| `fallback` | Initial in icon rail when the row has no icon. |
| `collapsed-hint` | Per-row tooltip bubble when `collapsedHints="tooltip"` (`exportparts` from `<vu-tooltip>`). |

## Types

### `VuNavPanelChangeDetail`

```ts
{ value?: string; item?: VuNavPanelItem; }
```

### `VuNavPanelCollapseChangeDetail`

```ts
{ collapsed: boolean; }
```

### `VuNavPanelCollapsedHints`

```ts
"none" | "tooltip" | "native"
```

### `VuNavPanelColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuNavPanelHintPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuNavPanelSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/nav-panel
- Markdown: https://velkinui.com/component/nav-panel.md

---

# Navbar

A responsive navbar component with desktop menus and a mobile drawer.

- **Tag:** `vu-navbar`
- **Slug:** `navbar`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuNavbar` from `@velkin/react/navbar`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuNavbar } from "@velkin/react/navbar";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `VuNavbarItem[]` | `[]` | Full menu item model. |
| `variant` | `VuNavbarVariant` | `"flat"` | Bar surface recipe (`flat`/`outline`/`elevated` plus chrome extras `transparent`/`inset`). Default: `"flat"`. |
| `tone` | `VuNavbarTone` | `"normal"` | Neutral surface weight; also relays into flyout panels. Default: `"normal"`. |
| `size` | `VuNavbarSize` | `"md"` | Bar height and link padding scale; also relays into flyout panels. Default: `"md"`. |
| `indicator` | `VuNavbarIndicator` | `"underline"` | Active top-level link affordance (`underline`/`pill`/`dot`/`none`); `pill` is selection chrome — not `radius="full"`. Default: `"underline"`. |
| `contained` | `boolean` | `false` | Centers the bar row with a max inline width. Default: `false`. |
| `activeRoute` | `string \| null` | `null` | Active route for highlighting (`activeroute` attr). |
| `breakpoint` | `number` | `768` | Mobile breakpoint in pixels. Default: `768`. |
| `isMobile` | `boolean` | `false` | Mobile layout flag (`ismobile` attr). |
| `overflowThreshold` | `number` | `0` | Minimum visible items before overflow mode. Default: `0`. |
| `justifyBar` | `string` | `"space-between"` | CSS `justify-content` for the outer bar (`justifybar` attr). |
| `justifyBarItems` | `string` | `"center"` | CSS `justify-content` for the item row (`justifybaritems` attr). |
| `pwaOverlay` | `boolean` | `false` | Window-controls-overlay placement (`pwaoverlay` attr). Default: `false`. |
| `customEvent` | `boolean` | `false` | Emits `vu-activate` instead of `vu-navigate` (`customevent` attr). Default: `false`. |
| `menuTrigger` | `VuNavbarMenuTrigger` | `"hover"` | Desktop submenu open interaction (`menutrigger` attr). Default: `"hover"`. |
| `placement` | `VuNavbarPlacement` | `"bottom"` | Preferred side for top dropdown. Default: `"bottom"`. |
| `align` | `VuNavbarAlign` | `"start"` | Alignment along the trigger edge. Default: `"start"`. |
| `offset` | `number` | `8` | Gap in px between trigger and dropdown. Default: `8`. |
| `sticky` | `boolean` | `false` | Pins to the top of the scroll container. Default: `false`. |
| `condense` | `boolean` | `false` | Elevates and shortens the bar when `sticky`. Default: `false`. |
| `arialabel` | `string` | — | Mobile drawer accessible name (`arialabel` attr). |
| `menuLabel` | `string` | `""` | Mobile menu toggle accessible name (`menulabel` attr). |
| `closeLabel` | `string` | `""` | Mobile drawer close accessible name (`closelabel` attr). |
| `menubarLabel` | `string` | `""` | Desktop menubar row accessible name (`menubarlabel` attr). |
| `ariaLabel` | `string` | `""` | Mobile drawer accessible name. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-navigate` | `VuNavbarNavigateDetail` | When a route item is activated. |
| `vu-activate` | `VuNavbarItemActivateDetail` | When an item is activated in `customEvent` mode. |

## Slots

| Name | Description |
| --- | --- |
| `prepend` | Content before navigation items on desktop. |
| `append` | Content after navigation items on desktop. |
| `prepend-mobile` | Content before navigation items in mobile mode. |
| `append-mobile` | Content after navigation items in mobile mode. |
| `header` | Header content for the mobile drawer. |
| `footer` | Footer content for the mobile drawer. |

## Methods

| Name | Description |
| --- | --- |
| `openMenu` | - Opens the mobile drawer menu. |
| `closeMenu` | - Closes mobile drawer and desktop submenus. |
| `toggleMenu` | - Toggles the mobile drawer menu. |
| `closeMenus` | - Closes all open menus. |

## CSS parts

| Name | Description |
| --- | --- |
| `nav-desktop` | Desktop navigation container. |
| `nav-mobile` | Mobile navigation container. |
| `nav-bar` | Navigation bar container. |
| `nav-link` | Desktop top-level nav control. |
| `top-menu` | Desktop dropdown panel. |
| `nested-menu` | Nested flyout panel. |

## Types

### `string | null`

```ts
null | string
```

### `VuNavbarAlign`

```ts
"start" | "center" | "end"
```

### `VuNavbarIndicator`

```ts
"none" | "dot" | "underline" | "pill"
```

### `VuNavbarItemActivateDetail`

```ts
{ item: VuNavbarItem; path: string | null; }
```

### `VuNavbarMenuTrigger`

```ts
"auto" | "click" | "hover"
```

### `VuNavbarNavigateDetail`

```ts
{ route: string; }
```

### `VuNavbarPlacement`

```ts
"top" | "bottom" | "left" | "right" | "auto"
```

### `VuNavbarSize`

```ts
"sm" | "md" | "lg"
```

### `VuNavbarTone`

```ts
"subtle" | "normal" | "strong"
```

### `VuNavbarVariant`

```ts
"outline" | "flat" | "elevated" | "transparent" | "inset"
```

## Links

- Docs: https://velkinui.com/component/navbar
- Markdown: https://velkinui.com/component/navbar.md

---

# Pagination

A pagination component with page numbers and optional jump field.

- **Tag:** `vu-pagination`
- **Slug:** `pagination`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuPagination` from `@velkin/react/pagination`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuPagination } from "@velkin/react/pagination";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `totalPages` | `number` | `5` | Total number of pages. |
| `currentPage` | `number` | `1` | Selected page (1-based). |
| `disabledPages` | `number[]` | `[]` | Page numbers that cannot be selected. |
| `loading` | `boolean` | `false` | Blocks interaction and shows the overlay spinner. |
| `progress` | `boolean` | `false` | Renders a progress track under the controls. |
| `layout` | `VuPaginationLayout` | `"bar"` | `bar` numbered buttons or `menu` page picker. |
| `jump` | `boolean` | `false` | Shows the jump-to-page field when `true` and `totalPages > 1`. |
| `size` | `VuPaginationSize` | `"md"` | Control density (`sm`, `md`, `lg`). |
| `radius` | `VuPaginationRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `maxVisiblePages` | `number` | `5` | Max numbered buttons before ellipsis collapse. |
| `label` | `string` | `""` | Accessible name for the navigation region. |
| `prevLabel` | `string` | `""` | Accessible name for the previous-page control. |
| `nextLabel` | `string` | `""` | Accessible name for the next-page control. |
| `jumpLabel` | `string` | `""` | Visible label for the jump field (`Page` by default). |
| `jumpGoLabel` | `string` | `""` | Label for the jump submit control (`Go` by default). |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuPaginationChangeDetail` | When `currentPage` changes. |

## Methods

| Name | Description |
| --- | --- |
| `nextPage` | - Moves to the next enabled page. |
| `prevPage` | - Moves to the previous enabled page. |
| `setPage` | - Moves to a specific enabled page. |

## CSS parts

| Name | Description |
| --- | --- |
| `base` | Outer wrapper. |
| `overlay` | Loading scrim over the controls. |
| `spinner` | Spinner centered in the overlay. |
| `block` | Interactive region dimmed while loading. |
| `bar` | Numbered bar layout container. |
| `pages` | Row of page buttons and decorative ellipsis markers. |
| `ellipsis` | Decorative truncated-range marker (`aria-hidden`). |
| `prev` | Previous-page control. |
| `next` | Next-page control. |
| `page` | Numbered page control. |
| `jump` | Jump-to-page field group. |
| `jump-label` | Visible label for the jump field. |
| `jump-input` | Jump-to-page number input. |
| `jump-go` | Jump submit control. |
| `picker` | Menu layout container. |
| `trigger` | Current-page trigger for the picker menu. |
| `menu` | Popover menu listing all pages. |
| `progress` | Optional progress track under the controls. |
| `fill` | Filled portion of the progress track. |

## Types

### `VuPaginationChangeDetail`

```ts
{ currentPage: number; }
```

### `VuPaginationLayout`

```ts
"menu" | "bar"
```

### `VuPaginationRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuPaginationSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/pagination
- Markdown: https://velkinui.com/component/pagination.md

---

# Speeddial

A speed dial component that expands into contextual quick actions.

- **Tag:** `vu-speeddial`
- **Slug:** `speeddial`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuSpeeddial` from `@velkin/react/speeddial`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSpeeddial } from "@velkin/react/speeddial";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Whether the action cluster is open. |
| `direction` | `VuSpeeddialDirection` | `"top"` | Preferred expansion side before viewport flip. |
| `color` | `VuSpeeddialColor` | `"primary"` | FAB intent color; defaults to `"primary"`. |
| `size` | `VuSpeeddialSize` | `"md"` | FAB and action hit-target scale. |
| `icon` | `string` | `"ion:add"` | Iconify name for the FAB icon when closed. |
| `iconOpen` | `string` | `"ion:close"` | Iconify name when open (defaults to `ion:close`). |
| `label` | `string` | `""` | Accessible name for the FAB (required when icon-only). |
| `closeOnEsc` | `boolean` | `true` | Whether Escape closes the open cluster. |
| `closeOnOutside` | `boolean` | `true` | Whether pointer-down outside closes the open cluster. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-open` | `void` | When the cluster begins opening. |
| `vu-close` | `void` | When the cluster begins closing. |
| `vu-open-change` | `VuSpeeddialOpenChangeDetail` | When `open` changes. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Action buttons (`<button>` or `<vu-button>`) shown when open. |

## Methods

| Name | Description |
| --- | --- |
| `show` | - Opens the speed dial when actions are slotted. |
| `hide` | - Closes the speed dial. |
| `toggle` | - Toggles the speed dial. |

## CSS parts

| Name | Description |
| --- | --- |
| `root` | Positioning wrapper around the FAB and action cluster. |
| `fab` | Native toggle button for the speed dial. |
| `actions` | Container for slotted action buttons. |

## Types

### `VuSpeeddialColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuSpeeddialDirection`

```ts
"top" | "bottom" | "left" | "right"
```

### `VuSpeeddialOpenChangeDetail`

```ts
{ open: boolean; direction: VuSpeeddialDirection; }
```

### `VuSpeeddialSize`

```ts
"sm" | "md" | "lg"
```

## Links

- Docs: https://velkinui.com/component/speeddial
- Markdown: https://velkinui.com/component/speeddial.md

---

# Steps

A steps component with horizontal or vertical multi-step navigation.

- **Tag:** `vu-steps`
- **Slug:** `steps`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuSteps` from `@velkin/react/steps`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuSteps } from "@velkin/react/steps";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `VuStepStateItem[]` | `[]` | Step list when the default slot has no `<vu-step-item>` children. |
| `currentStep` | `number` | `1` | Active step index (1-based). |
| `defaultCurrentStep` | `number` | `1` | Initial / reset step for `reset()`. |
| `lastCompletedStep` | `number` | `0` | Furthest step the user may advance to when `allowStepJump` is false; `0` derives from `currentStep`. |
| `layout` | `VuStepsLayout` | `"horizontal"` | `horizontal` (default) or `vertical`. |
| `labelPlacement` | `VuStepsLabelPlacement` | `"inline"` | `inline` (default) or `below` the node. |
| `size` | `VuStepsSize` | `"md"` | `sm`, `md` (default), or `lg`. |
| `variant` | `VuStepsVariant` | `"default"` | `default`, `dots`, or `progress`. |
| `allowStepJump` | `boolean` | `true` | When false, only adjacent / completed steps are reachable. |
| `hideNumbers` | `boolean` | `false` | Show bullets instead of numbers when no icons are set. |
| `showLabels` | `boolean` | `true` | Show step labels beside indicators. Default: true. |
| `compact` | `boolean` | `false` | Tighter spacing between steps. |
| `readonly` | `boolean` | `false` | Progress display only; steps are not interactive. |
| `expandAll` | `boolean` | `false` | Keep every vertical step panel open (docs / overview). |
| `label` | `string` | `""` | Accessible name for the step navigator. |
| `completedSteps` | `number[] \| null` | `null` | Explicit completed indices; overrides auto completion. |
| `stepIcon` | `string` | `""` | Default inactive icon for all steps. |
| `checkedIcon` | `string` | `""` | Default completed icon for all steps. |
| `errorIcon` | `string` | `""` | Default error icon for failed steps. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuStepsChangeDetail` | User-driven step changes; call `detail.cancel()` to block. |

## Slots

| Name | Description |
| --- | --- |
| `before` | Content before the step navigator. |
| `after` | Content after the step navigator. |
| `—` | - `<vu-step-item>` steps; when assigned, replaces the `steps` prop. |

## Methods

| Name | Description |
| --- | --- |
| `previous` | - Moves to the previous enabled step. |
| `next` | - Moves to the next enabled step. |
| `prevStep` | - Alias for `previous()`. |
| `nextStep` | - Alias for `next()`. |
| `goToStep` | - Navigates to a target step when allowed. |
| `getCurrentStep` | - Returns the current 1-based step index. |
| `focusStep` | - Focuses the header for the current step. |
| `reset` | - Restores `currentStep` from `defaultCurrentStep`. |

## CSS parts

| Name | Description |
| --- | --- |
| `steps` | Horizontal step navigator row. |
| `panels` | Panel stack container. |
| `panel` | Individual step panel. |
| `base` | Step header button (prop mode). |
| `node` | Circular step indicator (prop mode). |
| `labels` | Label stack (prop mode). |

## Types

### `number[] | null`

```ts
null | number[]
```

### `VuStepsChangeDetail`

```ts
{ step: number; previous: number; cancel: () => void; }
```

### `VuStepsLabelPlacement`

```ts
"inline" | "below"
```

### `VuStepsLayout`

```ts
"horizontal" | "vertical"
```

### `VuStepsSize`

```ts
"sm" | "md" | "lg"
```

### `VuStepsVariant`

```ts
"default" | "dots" | "progress"
```

## Links

- Docs: https://velkinui.com/component/steps
- Markdown: https://velkinui.com/component/steps.md

---

# Tab

A tab component with animated thumb and keyboard navigation.

- **Tag:** `vu-tab`
- **Slug:** `tab`
- **Category:** Navigation
- **Tier:** MIT
- **React:** `VuTab` from `@velkin/react/tab`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuTab } from "@velkin/react/tab";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `states` | `VuTabStateItem[]` | `[]` | Segment list when the default slot is empty. Default: `[]`. |
| `value` | `string \| undefined` | `undefined` | Selected segment when controlled; omit for uncontrolled mode. |
| `defaultValue` | `string` | `""` | Initial selection when uncontrolled. Default: `""`. |
| `disabled` | `boolean` | `false` | Disables every segment. Default: `false`. |
| `label` | `string` | `""` | Accessible name when no visible group label exists. Default: `""`. |
| `size` | `VuTabSize` | `"sm"` | Padding/type preset; `sm`\|`md`\|`lg` align with list/tree, `xs`/`xl` are density extras. Default: `"sm"`. |
| `orientation` | `VuTabOrientation` | `"horizontal"` | Horizontal row or vertical stack. Default: `"horizontal"`. |
| `stretch` | `boolean` | `false` | Fills container width; horizontal segments share space equally. Default: `false`. |
| `gap` | `string` | `""` | Spacing between segments; empty for flush layout. Default: `""`. |
| `radius` | `VuTabRadius` | `"full"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `"full"`. |
| `showCurrentLabelOnly` | `boolean` | `false` | Hides inactive labels. Default: `false`. |
| `iconOnly` | `boolean` | `false` | Square 1:1 segments; labels stay for a11y only. Default: `false`. |
| `color` | `VuTabColor` | `"primary"` | Thumb intent token; per-item color overrides. Default: `"primary"`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-change` | `VuTabChangeDetail` | User-driven selection changes only. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - `<vu-tab-item>` segments; when assigned, replaces the `states` prop. |

## Methods

| Name | Description |
| --- | --- |
| `focusSegment` | - Focuses the currently selected segment. |
| `reset` | - Restores uncontrolled selection from `defaultValue`. |

## CSS parts

| Name | Description |
| --- | --- |
| `wrap` | Outer radiogroup wrapper. |
| `indicator` | Sliding highlight behind the active segment. |
| `thumb` | Alias for the sliding indicator. |
| `base` | Each segment button in prop mode. |
| `base--selected` | Currently selected segment button. |
| `label` | Optional label span inside each button. |
| `icon` | Optional icon inside each button. |

## Types

### `string | undefined`

```ts
undefined | string
```

### `VuTabChangeDetail`

```ts
{ value: string; previous: string; index: number; item: VuTabNormalizedItem; source: HTMLElement | null; }
```

### `VuTabColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuTabOrientation`

```ts
"horizontal" | "vertical"
```

### `VuTabRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuTabSize`

```ts
"sm" | "md" | "lg" | "xs" | "xl"
```

## Links

- Docs: https://velkinui.com/component/tab
- Markdown: https://velkinui.com/component/tab.md

---

# Theming

# Config Provider

A config provider component for component defaults and presets.

- **Tag:** `vu-config-provider`
- **Slug:** `config-provider`
- **Category:** Theming
- **Tier:** MIT
- **React:** `VuConfigProvider` from `@velkin/react/config-provider`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuConfigProvider } from "@velkin/react/config-provider";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `presets` | `ComponentPresetsConfig` | — | Global `defaults` and named `presets` keyed by tag (`vu-button`) or short alias (`button`).

Hosts subscribe via `@lit/context`. Defaults apply with no extra attributes. `preset="name"` selects a named bag and is omitted from the DOM while empty. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - Content that receives merged component preset context. |

## CSS parts

| Name | Description |
| --- | --- |
| `—` | - None; this host is a context shell. |

## Links

- Docs: https://velkinui.com/component/config-provider
- Markdown: https://velkinui.com/component/config-provider.md

---

# Theme Provider

A theme provider component that supplies tokens and locale.

- **Tag:** `vu-theme-provider`
- **Slug:** `theme-provider`
- **Category:** Theming
- **Tier:** MIT
- **React:** `VuThemeProvider` from `@velkin/react/theme-provider`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuThemeProvider } from "@velkin/react/theme-provider";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `theme` | `VuThemeConfig` | — | Brand seeds (`primary`, intents, `radius`, `spacing`, `tint`, fonts) plus optional per-mode seeds and raw `vars`. |
| `scope` | `VuThemeProviderScope` | `"root"` | Where CSS variables are applied. Default: `"root"`. |
| `preference` | `ThemePreference` | `"system"` | Stored UI preference. Default: `"system"`. |
| `persist` | `boolean` | `true` | Persists preference to localStorage when scope includes root. Default: `true`. |
| `broadcast` | `boolean` | `true` | Emits global theme events when the active mode changes. Default: `true`. |
| `locale` | `string` | `"en"` | BCP 47 locale for built-in `msg()` strings. Default: `"en"`. |
| `injectStyles` | `boolean` | `true` | When false, skips injected token styles. Default: `true`. |
| `vibrantpalette` | `boolean` | `false` | Higher-contrast soft intent foregrounds. Default: `false`. |
| `glass` | `boolean` | `true` | App-wide glassmorphism for elevated surfaces and overlays. Does not paint a page background gradient — set your own. Default: `true`. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-theme` | `VuThemeProviderChangeDetail` | Bubbles when broadcast is true. |

## Slots

| Name | Description |
| --- | --- |
| `—` | - App subtree that inherits theme tokens and locale. |

## Methods

| Name | Description |
| --- | --- |
| `setPreference` | - Sets preference, optionally persists, and emits theme events when broadcast is true. |
| `togglePreference` | - Cycles preference light, dark, then system. |

## Types

### `ThemePreference`

```ts
"light" | "dark" | "system"
```

### `VuThemeProviderChangeDetail`

```ts
{ mode: "light" | "dark"; preference: ThemePreference; }
```

### `VuThemeProviderScope`

```ts
"both" | "root" | "host"
```

## Links

- Docs: https://velkinui.com/component/theme-provider
- Markdown: https://velkinui.com/component/theme-provider.md

---

# Theme Switcher

A theme switcher component for light, dark, and system modes.

- **Tag:** `vu-theme-switcher`
- **Slug:** `theme-switcher`
- **Category:** Theming
- **Tier:** MIT
- **React:** `VuThemeSwitcher` from `@velkin/react/theme-switcher`

## Import

```bash
npm i @velkin/react
```

```tsx
import { VuThemeSwitcher } from "@velkin/react/theme-switcher";
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `darkIcon` | `"ion:moon-outline"` | `"ion:moon-outline"` | Iconify id for dark preference. |
| `lightIcon` | `"ion:sunny-outline"` | `"ion:sunny-outline"` | Iconify id for light preference. |
| `systemIcon` | `"ion:desktop-outline"` | `"ion:desktop-outline"` | Iconify id for system preference. |
| `type` | `VuThemeSwitcherType` | `"button"` | `button` cycles on click; `switch` shows all three options. |
| `color` | `VuThemeSwitcherColor` | `"default"` | Token intent forwarded to the active control. |
| `disabled` | `boolean` | `false` | Disables interaction. Default: `false`. |
| `size` | `VuThemeSwitcherSize` | `"md"` | Child button / tab size. |
| `variant` | `VuThemeSwitcherVariant` | `"ghost"` | Visual variant for `type="button"` only. |
| `radius` | `VuThemeSwitcherRadius` | `"md"` | Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. |
| `iconOnly` | `boolean` | `true` | Square icon segments in `type="switch"`; cycling button is always icon-only. |

## Events

| Name | Type | Description |
| --- | --- | --- |
| `vu-theme` | `VuThemeSwitcherChangeDetail` | Fired when the user changes preference. |

## Slots

| Name | Description |
| --- | --- |
| `icon` | Optional slot to override the cycling button icon (`type="button"` only). |

## Methods

| Name | Description |
| --- | --- |
| `toggleTheme` | - Cycles preference light → system → dark and emits `vu-theme`. |

## CSS parts

| Name | Description |
| --- | --- |
| `container` | Wrapper around the control. |
| `button` | Cycling `<vu-button>` when `type="button"`. |
| `switch` | Segmented `<vu-tab>` when `type="switch"`. |
| `icon` | Theme icon inside the active control. |

## Types

### `VuThemeSwitcherChangeDetail`

```ts
{ preference: ThemePreference; mode: "light" | "dark"; }
```

### `VuThemeSwitcherColor`

```ts
"default" | "primary" | "success" | "warning" | "danger"
```

### `VuThemeSwitcherRadius`

```ts
"sm" | "md" | "lg" | "none" | "full"
```

### `VuThemeSwitcherSize`

```ts
"sm" | "md" | "lg"
```

### `VuThemeSwitcherType`

```ts
"button" | "switch"
```

### `VuThemeSwitcherVariant`

```ts
"solid" | "outline" | "soft" | "ghost" | "link"
```

## Links

- Docs: https://velkinui.com/component/theme-switcher
- Markdown: https://velkinui.com/component/theme-switcher.md

---