# oks-ui — full context

> oks-ui is a strict-TypeScript React component library with a CSS-variable
> design system. Zero runtime dependencies beyond React, no theme provider, no
> configuration, accessible by default. MIT licensed and free.
>
> Homepage: https://www.oks-ui.com
> Package: https://www.npmjs.com/package/oks-ui
> License: MIT

## What it is

oks-ui gives you ~65 ready-made React components (buttons, modals, drawers,
forms, tables, charts, toasts, a command palette, a Kanban board, a block
editor, and more) with a consistent design system driven entirely by CSS custom
properties. Every color, space, radius, and shadow is an `--oks-*` variable, so
theming needs no build step, no config object, and no React context.

Design goals:

- **Strict TypeScript.** Built with `noUncheckedIndexedAccess`,
  `exactOptionalPropertyTypes`, and the full strict suite. Props are stable and
  intentional.
- **Zero runtime dependencies.** Nothing ships to your bundle except the
  components themselves; the only peers are `react` and `react-dom`.
- **CSS-variable tokens.** Theme by overriding `--oks-*` properties from your own
  CSS. Semantic roles (`primary`, `secondary`, `success`, `warning`, `danger`,
  …) are aliases you can point at any palette.
- **Accessible by default.** Keyboard navigation, `:focus-visible` rings, ARIA
  roles, and `prefers-reduced-motion` support are built into every component.
- **Opt-in utilities.** A prefixed `.oks-*` utility layer is available as a
  separate CSS import for rapid prototyping alongside components.

## Install and use

```bash
npm install oks-ui
# or: pnpm add oks-ui   /   yarn add oks-ui
```

```ts
// Import the styles once, in your app entry or root layout:
import "oks-ui/styles.css";
```

```tsx
import { Button } from "oks-ui";

export function Example() {
  return <Button color="primary">Save</Button>;
}
```

No provider wrapper and no configuration are required. Components are named
exports from the package root: `import { Button, Modal, Table, Chart } from "oks-ui"`.
Per-component subpaths are also available if you only need one component and
its CSS: `import { Button } from "oks-ui/button"; import "oks-ui/button.css";`.

Style entry points:

- `oks-ui/styles.css` — tokens + utilities + component styles (recommended).
- `oks-ui/tokens.css` — just the `--oks-*` custom properties.
- `oks-ui/utilities.css` — just the prefixed `.oks-*` utility classes.
- `oks-ui/motion` — optional motion utilities.

Per-component entry points (oks-ui 1.2+): import just what you use, each with
its own stylesheet — `import { Button } from "oks-ui/button"` plus
`import "oks-ui/button.css"`. Every component has one (`oks-ui/table`,
`oks-ui/text-editor`, …); the `oks-ui` barrel keeps working.

Requires React 18 or newer. Works with the Next.js App Router (mark files that
render oks-ui components with `"use client"`; components carry no client
markers of their own).

## Theming

```css
:root {
  /* Override any token */
  --oks-color-primary-500: #7c3aed;
  --oks-space-4: 18px;

  /* Point a semantic role at a built-in palette */
  --oks-color-secondary-500: var(--oks-palette-slate-500);
}
```

Dark mode is driven by a `data-theme="dark"` attribute on `<html>`; token values
respond to it automatically. Built-in palettes include slate, gray, zinc,
neutral, stone, red, orange, amber, and more.

## Components (65)

Each component has an interactive props playground at
`https://www.oks-ui.com/components/<slug>/`.

### Actions
- **Button** (`/components/button`): A pressable element with variants, colors, sizes, loading state, and ripple feedback.
- **ButtonGroup** (`/components/button-group`): Merges adjacent Buttons into a single control, sharing variant/color/size defaults.

### Feedback
- **Alert** (`/components/alert`): Contextual feedback message with icon, title, description, and dismiss.
- **Toast** (`/components/toast`): Provider-based toast notification system with a promise-aware API.
- **Loader** (`/components/loader`): Loading spinner for indeterminate progress, with 7 built-in variants.
- **Modal** (`/components/modal`): Dialog modal with focus trapping, keyboard dismissal, and safe stacking.

### Navigation
- **Tabs** (`/components/tabs`): Tabbed content navigation with a composable, roving-tabindex API.
- **Drawer** (`/components/drawer`): Slide-in panel from any edge of the viewport, built on the same overlay stack as Modal.
- **Dropdown** (`/components/dropdown`): Menu dropdown with triggers, sections, submenus, and opt-in virtualization.
- **SteppedForm** (`/components/stepped-form`): Multi-step form flow with progress tracking, built on FormFieldSet.
- **Nav** (`/components/nav`): Multi-level navigation tree with collapsible groups, active-route styling, an accordion mode, and a collapsed icon rail.
- **Breadcrumbs** (`/components/breadcrumbs`): Navigation trail with a chevron separator, collapse-to-ellipsis, and router-link polymorphism.
- **Pagination** (`/components/pagination`): Windowed page-number control for a list or table footer, with a "Showing X–Y of Z" summary.
- **SegmentedControl** (`/components/segmented-control`): Compact inline switch between a few mutually exclusive options, with an animated selection thumb.
- **CommandPalette** (`/components/command-palette`): The Cmd+K overlay: a search box over a fuzzy-filtered, grouped list of actions and destinations, with full keyboard navigation and a useCommandPalette hotkey hook.

### Data Display
- **Badge** (`/components/badge`): Notification badge with count, dot, and placement, plus a bump animation on change.
- **Avatar** (`/components/avatar`): User avatar with group support, status indicator, and image-load fallback.
- **Chip** (`/components/chip`): Compact tag or pill element, closable and selectable.
- **Tooltip** (`/components/tooltip`): Hover/focus tooltip with positioning logic and touch-aware delays.
- **Table** (`/components/table`): Config-driven data table with sorting, row selection, row expansion, a sticky header, and loading and empty states.
- **EmptyState** (`/components/empty-state`): Centered placeholder for an empty or no-match list, with an icon, title, description, and actions.
- **Progress** (`/components/progress`): Linear and circular progress indicators, determinate or indeterminate, with an optional value label.
- **TreeView** (`/components/tree-view`): Hierarchy you can open, select and check, with check marks that roll up and children that load on demand.
- **DiffView** (`/components/diff-view`): Compares two texts line by line, side by side or in one column, with changed words highlighted and long unchanged stretches folded.
- **MediaLibrary** (`/components/media-library`): A grid of images and files to pick from, with search, type filters, one or many picks, load more and upload.
- **Accordion** (`/components/accordion`): Collapsible sections with single-open or multiple modes, three visual variants, and animated open/close.

### Data Visualization
- **Line Chart** (`/components/chart-line`): Chart type="line" -- ChartLineOptions: curve style and stroke width.
- **Area Chart** (`/components/chart-area`): Chart type="area" -- a line chart with the area under it filled automatically.
- **Bar Chart** (`/components/chart-bar`): Chart type="bar" -- ChartBarOptions: stacked series and corner radius.
- **Column Chart** (`/components/chart-column`): Chart type="column" -- ChartColumnOptions: stacked series and corner radius.
- **Pie Chart** (`/components/chart-pie`): Chart type="pie" -- ChartPieStyleOptions: slice border. Single series, one value per slice.
- **Donut Chart** (`/components/chart-donut`): Chart type="donut" -- ChartPieStyleOptions: slice border and inner ratio.
- **Heatmap Chart** (`/components/chart-heatmap`): Chart type="heatmap" -- ChartHeatmapOptions: series as rows, categories as columns, one hue scaled by opacity across the value domain.
- **Sparkline Chart** (`/components/chart-sparkline`): Chart type="sparkline" -- a small trend with no axes, legend or frame, for a table cell or a stat card.
- **Combo Chart** (`/components/chart-combo`): Chart type="combo" -- columns, lines and areas on one set of categories, with an optional second value axis on the right.
- **Chart States** (`/components/chart-states`): isLoading/error/empty -- real, separate props that each replace the chart entirely, shared across every chart type.

### Layout & Display
- **Divider** (`/components/divider`): Horizontal or vertical rule, with an optional inline label.
- **Backdrop** (`/components/backdrop`): Overlay backdrop for modals, drawers, and menus, with blur and stacking support.
- **PageTitle** (`/components/page-title`): Semantic page/section heading with an optional icon, subtitle, and tooltip.
- **Card** (`/components/card`): Bordered, rounded, elevated surface container, with header, body, and footer regions.
- **Stat** (`/components/stat`): KPI block with a label, value, trend delta pill, optional icon and sparkline, plus a responsive StatGroup.
- **Timeline** (`/components/timeline`): Vertical activity feed with dot or icon markers on a connector rail.
- **Calendar** (`/components/calendar`): Standalone month-grid view with single or range selection, min/max and per-day constraints, a renderDay slot for event markers, and full grid keyboard navigation.
- **SplitLayout** (`/components/split-layout`): Resizable multi-pane frame for email 3-pane, master-detail, and split editors, with keyboard-resizable dividers and collapsible panes.
- **Message** (`/components/message`): Chat message-thread primitives: a screen-reader-live MessageList and left/right-aligned Message bubbles with author, avatar, timestamp, delivery status, and continuation grouping.
- **Board** (`/components/board`): Data-driven Kanban board with dependency-free pointer, touch, and keyboard drag-and-drop, column card limits, and live-region announcements.
- **Skeleton** (`/components/skeleton`): Loading placeholder, as a shaped block or a wrapper that reveals its content once loaded.
- **Sortable** (`/components/sortable`): Reorder a list, row or grid by pointer, touch or keyboard, with every step announced to screen readers.
- **DropZone** (`/components/drop-zone`): Draggable items and drop areas that work with a pointer, a finger or the keyboard, and take files dropped from the computer.

### Forms
- **Rating** (`/components/rating`): Star rating you can set or show: whole or half stars, your own icon, keyboard and touch, and a field in Form.
- **ColorPicker** (`/components/color-picker`): Colour picker with a saturation area, hue and opacity sliders, hex, rgb or hsl text, swatches and an eye dropper, plus a ColorField for forms.
- **CodeField** (`/components/code-field`): Text field for code and settings with highlighting, line numbers, Tab to indent and a live JSON check, with no dependencies.
- **Text Field** (`/components/form-field-text`): FormFieldSet type="text" -- TextField, also covers number/url/search/color/email.
- **Textarea Field** (`/components/form-field-textarea`): FormFieldSet type="textarea" -- multi-line text with a length counter.
- **Select Field** (`/components/form-field-select`): FormFieldSet type="select" -- single/multi select with a custom popover or native mode.
- **Password Field** (`/components/form-field-password`): FormFieldSet type="password" -- reveal toggle and strong-password requirements.
- **OTP Field** (`/components/form-field-otp`): FormFieldSet type="otp" -- segmented or single-input one-time code entry.
- **Phone Field** (`/components/form-field-phone`): FormFieldSet type="phone" -- phone number with a country calling-code selector.
- **Range Field** (`/components/form-field-range`): FormFieldSet type="range" -- single or dual-thumb slider.
- **File Field** (`/components/form-field-file`): FormFieldSet type="file" -- inline or dropzone file upload with previews.
- **Switch Field** (`/components/form-field-switch`): FormFieldSet type="switch" -- toggle with optional on/off state text.
- **Radio Group Field** (`/components/form-field-radio`): FormFieldSet type="radio" -- single-select radio group.
- **Checkbox Group Field** (`/components/form-field-checkbox`): FormFieldSet type="checkbox" -- multi-select checkbox group.
- **Date Picker Field** (`/components/form-field-datepicker`): FormFieldSet type="datepicker" -- single date or range, with time and presets.

### Editors
- **TextEditor** (`/components/text-editor`): Block-based rich text editor (Notion-style) with 17 block types, slash-menu insertion, Markdown shortcuts, rich paste, and drag-and-drop reordering.

## Props reference

Prop name, type, default, and a one-line description for each component.
The full table for each is on its component page.

### Button (`/components/button`)
- `children` (`ReactNode`): Button label/content.
- `startContent` (`ReactNode`): Content rendered before the label.
- `endContent` (`ReactNode`): Content rendered after the label.
- `spinner` (`ReactNode`, default built-in spinner): Overrides the default loading spinner.
- `spinnerPlacement` (`"start" | "end"`, default start): Where the loading spinner renders relative to the label.
- `variant` (`"solid" | "soft" | "bordered" | "ghost" | "link"`, default solid): Visual style variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color.
- `colorDepth` (`50 | 100 | ... | 950`, default 500): Shade depth for the selected color.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Button size.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default md): Border radius.
- `shadow` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg"`, default none): Box-shadow depth.
- `fullWidth` (`boolean`, default false): Expands to fill available horizontal space.
- `isIconOnly` (`boolean`, default false): Renders a square icon button.
- `as` (`ElementType`, default href ? "a" : "button"): Render as a different element or component.
- `href` (`string`): Renders as an anchor when set.
- `target` (`string`): Anchor target.
- `rel` (`string`, default "noopener noreferrer" when target="_blank"): Anchor rel attribute.
- `download` (`string | boolean`): Anchor download attribute.
- `tooltip` (`ReactNode | boolean | (Omit<TooltipProps, "children"|"content"> & { content?: ReactNode })`): Wraps the button in the built-in Tooltip component when set.
- `isDisabled` (`boolean`, default false): Disables the button; sets aria-disabled + tabIndex=-1 when rendered as an anchor.
- `isLoading` (`boolean`, default false): Shows a spinner and sets aria-busy; stays focusable by design.
- `disableRipple` (`boolean`, default false): Disables the click ripple effect.
- `disableAnimation` (`boolean`, default false): Disables all transitions/animations, including the ripple.
- `onPress / onPressStart / onPressEnd / onPressUp / onPressChange` (`(e) => void`): Press-style callbacks alongside native onClick.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### ButtonGroup (`/components/button-group`)
- `children` (`ReactNode`): Buttons rendered inside the group.
- `variant` (`"solid" | "soft" | "bordered" | "ghost" | "link"`, default solid): Default variant for child Buttons that don't set their own.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Default color for child Buttons that don't set their own.
- `colorDepth` (`50 | 100 | ... | 950`): Optional default depth, only applied when provided.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Default size for child Buttons that don't set their own.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default md): Default radius for child Buttons that don't set their own.
- `fullWidth` (`boolean`, default false): Default fullWidth for child Buttons that don't set their own.
- `isDisabled` (`boolean`, default false): Disables all child Buttons that don't set isDisabled explicitly.
- `role` (`string`, default group): ARIA role for the group container.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Alert (`/components/alert`)
- `title` (`ReactNode`): Alert title.
- `description` (`ReactNode`): Alert body content.
- `icon` (`ReactNode`): Overrides the default color-derived status icon.
- `startContent` (`ReactNode`): Content rendered before the title/description block.
- `endContent` (`ReactNode`): Content rendered after the title/description block.
- `actions` (`ReactNode`): Action buttons rendered below the description.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color, also picks the default status icon.
- `variant` (`"solid" | "soft" | "bordered"`, default solid): Visual style variant.
- `shadow` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg"`, default none): Box-shadow depth.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default md): Border radius.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Alert size.
- `isVisible` (`boolean`): Controlled visibility; uncontrolled defaults visible.
- `isClosable` (`boolean`, default false): Shows a close button.
- `hideIcon` (`boolean`, default false): Hides the status icon entirely.
- `hideIconWrapper` (`boolean`, default false): Hides the icon's background wrapper, keeping the icon itself.
- `closeButtonProps` (`Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type">`): Extra props forwarded to the close button.
- `disableAnimation` (`boolean`, default false): Disables the enter/exit animation.
- `onClose` (`() => void`): Called when the close button is pressed.
- `onVisibleChange` (`(isVisible: boolean) => void`): Called whenever visibility changes.
- `classNames` (`Partial<Record<AlertSlot, string>>`): Per-slot class overrides.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Toast (`/components/toast`)
- `children` (`ReactNode`): Your app, rendered inside the provider.
- `position` (`"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"`, default "bottom-right"): Where the toast region renders.
- `maxToasts` (`number`, default 12): Total toasts kept in the queue (visible + pending).
- `maxVisibleToasts` (`number`, default 3): Toasts shown at once before stacking/queuing.
- `toastOffset` (`number`, default 0): Extra offset from the viewport edge.
- `container` (`Element | DocumentFragment | null`): Custom portal mount target.
- `defaultDuration` (`number`, default 6000): Auto-dismiss duration in ms, unless overridden per-toast or persistent.
- `toastProps` (`ToastOptions`): Default options applied to every toast from this provider.
- `motion` (`"auto" | "reduced" | "default"`, default "auto"): Animation mode; "auto" respects prefers-reduced-motion.
- `disableAnimation` (`boolean`, default false): Disables all toast animation.
- `regionProps` (`ToastRegionProps`): Extra props for the toast region container.
- `className` (`string`): Class applied to the toast region.
- `style` (`CSSProperties`): Inline styles for the toast region.
- `title` (`ReactNode`): Toast title.
- `description / message` (`ReactNode`): Toast body content.
- `icon` (`ReactNode`): Overrides the default type-derived icon.
- `showIcon / hideIcon` (`boolean`, default shown): Show or hide the icon slot; hideIcon wins when both are set.
- `loadingComponent` (`ReactNode`): Shown in the icon slot while type is "loading" (for example during a promise toast), instead of the status icon.
- `endContent` (`ReactNode`): Content rendered at the end of the toast.
- `action` (`{ label: string; onClick?: () => void }`): An inline action button.
- `type` (`"default" | "info" | "success" | "warning" | "error" | "loading"`, default derived from color, else "default"): Semantic type, also picks the default icon.
- `color` (`ToastColor`): Semantic color.
- `variant` (`"solid" | "soft" | "flat" | "bordered"`, default "flat"): Visual style variant.
- `radius` (`OksRadius`, default "md"): Border radius.
- `size` (`OksSize`, default "md"): Toast size.
- `position` (`ToastPosition`, default provider's position): Per-toast position override.
- `duration` (`number | null`, default 6000): Auto-dismiss duration in ms; null disables auto-dismiss.
- `persistent` (`boolean`, default false): Never auto-dismisses.
- `showDurationBar` (`boolean`, default false): Shows a countdown progress bar.
- `dismissible` (`boolean`, default true): Shows a close button.
- `promise` (`Promise<unknown>`): Drives the promise-aware loading/success/error flow.
- `onDismiss` (`(id: ToastId) => void`): Called when the toast is dismissed.
- `closeIcon` (`ReactNode`): Overrides the default close icon.
- `classNames` (`ToastClassNames`): Per-slot class overrides.
- `className` (`string`): Class applied to this toast's root element.

### Loader (`/components/loader`)
- `label` (`string`, default "Loading"): Accessible label (used with role="status").
- `variant` (`"ring-inset" | "ring-clip" | "ring-outset" | "ring-dual" | "pulse" | "dots-roll" | "dots-sweep"`, default ring-inset): Visual spinner style.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl" | number`, default "md" (40px)): Loader size; accepts a size token or a raw pixel number.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "white"`): Shorthand that sets both trackColor and indicatorColor.
- `trackColor` (`LoaderColor`, default color ?? "white"): Color of the loader's background track.
- `indicatorColor` (`LoaderColor`, default color ?? "default"): Color of the loader's moving indicator.
- `speed` (`string`, default "1s"): Animation duration, any valid CSS time value.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Modal (`/components/modal`)
- `title` (`ReactNode`): Header title.
- `children` (`ReactNode`): Body content.
- `actions` (`ReactNode`): Footer action buttons.
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "full" | string | number`, default md): Modal width.
- `blur` (`boolean | "sm" | "md" | "lg" | number`): Backdrop blur amount.
- `backgroundOpacity` (`number`): Backdrop opacity (0-100).
- `portal` (`boolean`, default true): Renders through a React portal.
- `container` (`Element | DocumentFragment | null`): Custom portal mount target.
- `zIndex` (`number`): Explicit stacking z-index; auto-computed when unset.
- `isOpen` (`boolean`): Controls whether the modal is open (required).
- `role` (`"dialog" | "alertdialog"`, default dialog): ARIA role.
- `dismissible` (`boolean`, default true): Shows a close button in the header.
- `closeLabel` (`string`, default "Close modal"): Accessible label for the close button.
- `closeOnOutsideClick` (`boolean`, default true): Closes on backdrop click.
- `closeOnEscape` (`boolean`, default true): Closes on Escape.
- `initialFocusRef` (`RefObject<HTMLElement | null>`): Element to focus when the modal opens.
- `animationDuration` (`number`): Enter/exit animation duration in seconds.
- `animationType` (`"fade" | "zoom" | "slideUp" | "slideDown" | "slideLeft" | "slideRight"`): Backdrop entrance/exit animation.
- `easing` (`"ease" | "easeIn" | "easeOut" | "easeInOut"`): Animation easing curve.
- `onClose` (`() => void`): Called to close the modal (required).
- `backdrop` (`Partial<BackdropProps>`): Extra props forwarded to the underlying Backdrop.
- `headers` (`Partial<PageTitleProps>`): Extra props forwarded to the header's PageTitle.
- `divider` (`Partial<DividerProps>`): Extra props for the header/body divider.
- `classNames` (`Partial<Record<ModalSlot, string>>`): Per-slot class overrides (base/header/headerTitle/body/footer/closeButton).
- `className` (`string`): Class applied to the root modal element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Tabs (`/components/tabs`)
- `children` (`ReactNode | ((item: T) => ReactElement)`): Declarative <Tab> children, or a render function with items.
- `items` (`Iterable<T>`): Dynamic items, used with a render-function children.
- `variant` (`"solid" | "bordered" | "light" | "underlined"`, default solid): Visual style variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Tab list size.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default full): Border radius.
- `fullWidth` (`boolean`, default false): Stretches tabs to fill the available width.
- `placement` (`"top" | "bottom" | "start" | "end"`, default top): Tab list position relative to panels.
- `isVertical` (`boolean`, default false): Renders a vertical tab list.
- `disabledKeys` (`Key[]`): Keys of tabs to disable.
- `selectedKey` (`Key`): Controlled selected tab key.
- `defaultSelectedKey` (`Key`): Uncontrolled initial selected tab key.
- `shouldSelectOnPressUp` (`boolean`, default true): Selects on pointer-up rather than pointer-down.
- `keyboardActivation` (`"automatic" | "manual"`, default automatic): Whether arrow-key focus also selects, or only Enter/Space does.
- `isDisabled` (`boolean`, default false): Disables the whole tab list.
- `destroyInactiveTabPanel` (`boolean`, default false): Unmounts inactive panels instead of hiding them.
- `disableCursorAnimation` (`boolean`, default false): Disables the sliding active-tab cursor animation.
- `disableAnimation` (`boolean`, default false): Disables all animation, including the cursor.
- `onSelectionChange` (`(key: Key) => void`): Called when the selected tab changes.
- `classNames` (`TabsClassNames`): Per-slot class overrides (base/tabList/tab/tabContent/cursor/panel/tabWrapper).
- `className` (`string`): Class applied to the root element.
- `title` (`ReactNode`): Tab label (required).
- `titleValue` (`string`): Plain-text override of title, used for accessible naming when title is a node.
- `children` (`ReactNode`): Panel content for this tab.
- `href / target / rel / download / ping / referrerPolicy` (`string`): Renders the tab as a link when href is set.
- `isDisabled` (`boolean`, default false): Disables this specific tab.
- `shouldSelectOnPressUp` (`boolean`): Per-tab override of the Tabs-level setting.

### Drawer (`/components/drawer`)
- `title` (`ReactNode`): Header title.
- `children` (`ReactNode`): Body content.
- `actions` (`ReactNode`): Footer action buttons.
- `blur` (`boolean | "sm" | "md" | "lg" | number`): Backdrop blur amount.
- `backgroundOpacity` (`number`): Backdrop opacity (0-100).
- `position` (`"left" | "right" | "top" | "bottom"`, default right): Edge the drawer slides in from.
- `width` (`"xs" | "sm" | "md" | "lg" | "xl" | "full" | string | number`, default "420px"): Panel width, for left/right positions.
- `height` (`"xs" | "sm" | "md" | "lg" | "xl" | "full" | string | number`, default "360px"): Panel height, for top/bottom positions.
- `portal` (`boolean`, default true): Renders through a React portal.
- `container` (`Element | DocumentFragment | null`): Custom portal mount target.
- `zIndex` (`number`): Explicit stacking z-index; auto-computed when unset.
- `isOpen` (`boolean`): Controls whether the drawer is open (required).
- `ariaLabel` (`string`, default "Drawer"): Accessible name for the drawer region.
- `dismissible` (`boolean`, default true): Shows a close button in the header.
- `closeLabel` (`string`, default "Close drawer"): Accessible label for the close button.
- `closeOnOutsideClick` (`boolean`, default true): Closes on backdrop click.
- `closeOnEscape` (`boolean`, default true): Closes on Escape.
- `initialFocusRef` (`RefObject<HTMLElement | null>`): Element to focus when the drawer opens.
- `animationDuration` (`number`): Enter/exit animation duration in seconds.
- `easing` (`"ease" | "easeIn" | "easeOut" | "easeInOut"`): Animation easing curve.
- `onClose` (`() => void`): Called to close the drawer (required).
- `backdrop` (`Partial<BackdropProps>`): Extra props forwarded to the underlying Backdrop.
- `headers` (`Partial<PageTitleProps>`): Extra props forwarded to the header's PageTitle.
- `divider` (`Partial<DividerProps>`): Extra props for the header/body divider.
- `classNames` (`Partial<Record<DrawerSlot, string>>`): Per-slot class overrides (base/header/headerTitle/body/footer/closeButton).
- `className` (`string`): Class applied to the root drawer element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Dropdown (`/components/dropdown`)
- `children` (`ReactNode`): A DropdownTrigger and a DropdownMenu.
- `placement` (`"bottom-start" | "bottom-end" | "top-start" | ... (12-way)`, default "bottom-start"): Menu position relative to the trigger.
- `offset` (`number`, default 8): Distance from the trigger.
- `containerPadding` (`number`, default 8): Minimum distance kept from the viewport edge.
- `shouldFlip` (`boolean`, default true): Flips placement to stay in the viewport.
- `portalContainer` (`Element | DocumentFragment | null`): Custom portal mount target.
- `isOpen` (`boolean`): Controlled open state.
- `defaultOpen` (`boolean`, default false): Uncontrolled initial open state.
- `isDismissable` (`boolean`, default true): Allows dismissing via outside click/Escape.
- `isKeyboardDismissDisabled` (`boolean`, default false): Disables closing via Escape.
- `shouldCloseOnInteractOutside` (`(target: Element) => boolean`): Custom predicate for outside-interaction dismissal.
- `closeOnSelect` (`boolean`, default true): Closes the menu after an item is selected.
- `onOpenChange` (`(isOpen: boolean) => void`): Called when open state changes.
- `classNames` (`Partial<Record<"base" | "content", string>>`): Per-slot class overrides.
- `className` (`string`): Class applied to the root.
- `style` (`CSSProperties`): Inline styles for the root.
- `children` (`ReactElement`): The single element that opens the menu on press (required).
- `children` (`ReactNode | ((item: T) => ReactElement)`): Declarative DropdownItem/DropdownSection children, or a render function with items.
- `items` (`Iterable<T>`): Dynamic items, used with a render-function children.
- `topContent / bottomContent` (`ReactNode`): Content rendered above/below the item list.
- `emptyContent` (`ReactNode`, default "No items."): Shown when there are no items.
- `variant` (`"solid" | "bordered" | "light" | "flat" | "faded" | "shadow"`, default solid): Visual style variant.
- `color` (`DropdownColor`, default default): Semantic color.
- `hideSelectedIcon` (`boolean`, default false): Hides the selected-item checkmark.
- `selectionMode` (`"none" | "single" | "multiple"`, default none): Item selection behavior.
- `selectedKeys` (`"all" | Iterable<Key>`): Controlled selected keys.
- `defaultSelectedKeys` (`"all" | Iterable<Key>`): Uncontrolled initial selected keys.
- `disabledKeys` (`Iterable<Key>`): Keys of items to disable.
- `disallowEmptySelection` (`boolean`, default false): Prevents deselecting the last selected item.
- `autoFocus` (`boolean | "first" | "last"`, default false): Focuses an item automatically when the menu opens.
- `hideEmptyContent` (`boolean`, default false): Hides the empty-state content entirely.
- `shouldFocusWrap` (`boolean`, default false): Wraps keyboard focus from the last item to the first.
- `closeOnSelect` (`boolean`, default parent Dropdown's value): Per-menu override of the root's closeOnSelect.
- `virtualization` (`{ itemHeight: number; overscan?: number }`): Enables fixed-height virtualized rendering for long lists.
- `disableAnimation` (`boolean`, default false): Disables the menu's open animation.
- `onAction` (`(key: Key) => void`): Called when an item is activated.
- `onSelectionChange` (`(keys) => void`): Called when selection changes.
- `onClose` (`() => void`): Called when the menu requests to close.
- `classNames` (`DropdownMenuClassNames`): Per-slot class overrides (base/list/emptyContent).
- `itemClasses` (`Partial<Record<DropdownItemSlot, string>>`): Per-slot class overrides applied to every item.
- `children / title` (`ReactNode`): Item label.
- `textValue` (`string`): Plain-text override for typeahead/accessible naming.
- `description` (`ReactNode`): Secondary text below the label.
- `shortcut` (`ReactNode`): Keyboard shortcut hint.
- `startContent / endContent` (`ReactNode`): Content rendered before/after the label.
- `selectedIcon` (`ReactNode`): Overrides the default selected checkmark.
- `submenuPlacement` (`DropdownPlacement`, default "right-start"): Position of a nested DropdownMenu, when this item has one.
- `showDivider` (`boolean`, default false): Shows a divider below this item.
- `href / target / rel / download / ping / referrerPolicy` (`string`): Renders the item as a link when href is set.
- `isDisabled` (`boolean`, default false): Disables this item.
- `isReadOnly` (`boolean`, default false): Not selectable, but not visually disabled.
- `isSelected` (`boolean`): Marks this item as selected.
- `closeOnSelect` (`boolean`): Per-item override of the menu's closeOnSelect.
- `itemKey` (`Key`): Explicit key, when not using items+render-function.
- `onAction / onClose / onClick / onPress / onPressStart / onPressEnd / onPressChange / onPressUp / onKeyDown / onKeyUp` (`callback`): Interaction callbacks.

### SteppedForm (`/components/stepped-form`)
- `steps` (`SteppedFormStep[]`): Ordered step definitions: { key, title, description?, fields?, content, isOptional?
- `backLabel / nextLabel / submitLabel` (`ReactNode`, default "Back" / "Next" / "Submit"): Footer action button labels.
- `headerVariant` (`"dots" | "progress" | "tabs" | "none"`, default "dots"): Built-in step-header style.
- `initialStep` (`number`, default 0): Uncontrolled initial step index.
- `stepIndex` (`number`): Controlled current step index.
- `disableHeaderNavigation` (`boolean`, default false): Prevents jumping steps by clicking the header.
- `renderHeader` (`(args) => ReactNode`): Fully custom header renderer, replacing headerVariant.
- `renderStepHeaderItem` (`(args) => ReactNode`): Custom renderer for a single step-header item.
- `validationMode / showErrorsOn / initialValues / ...` (`see Form props`, default see Form): All other Form props are inherited (steps replaces children).
- `onStepChange` (`(nextIndex: number) => void`): Called when the active step changes.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Inherited from Form — called on final-step submit (required).
- `classNames` (`Partial<Record<SteppedFormSlot, string>>`): Per-slot class overrides (11 slots: base/header/steps/stepButton/stepDot/stepLabel/stepDescription/progress/progressTrack/progressIndicator/content/footer/ac...
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Badge (`/components/badge`)
- `children` (`ReactNode`): Element the badge is anchored to.
- `content` (`string | number | ReactNode`): Badge content; omit with isDot for a plain dot.
- `max` (`number`): Caps a numeric content at max+ (e.g.
- `variant` (`"solid" | "soft" | "bordered"`, default solid): Visual style variant.
- `shadow` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg"`, default none): Box-shadow depth.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Badge size.
- `shape` (`"circle" | "rectangle"`, default rectangle): Badge shape.
- `isOneChar` (`boolean`, default false): Forces a perfectly circular badge sized for one character.
- `placement` (`"top-start" | "top-end" | "bottom-start" | "bottom-end" | ...`, default "top-end"): Corner the badge anchors to, relative to children.
- `offset` (`number`, default 0): Extra offset along the placement's main axis.
- `crossOffset` (`number`, default 0): Extra offset along the placement's cross axis.
- `showOutline` (`boolean`, default true): Shows a ring around the badge separating it from its content.
- `disableOutline` (`boolean`, default false): Alias to force-disable the outline.
- `isInvisible` (`boolean`, default false): Hides the badge without unmounting it.
- `isDot` (`boolean`, default false): Renders a plain status dot instead of content.
- `ariaLabel` (`string`): Accessible label for the badge indicator.
- `disableAnimation` (`boolean`, default false): Disables the bump animation on content change.
- `classNames` (`Partial<Record<"base" | "badge", string>>`): Per-slot class overrides.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Avatar (`/components/avatar`)
- `name` (`string`): Used to derive fallback initials.
- `src` (`string`): Image source URL.
- `icon` (`ReactNode`): Custom fallback icon, used when name/initials aren't available.
- `fallback` (`ReactNode`): Fully custom fallback content, overrides icon/initials.
- `showFallback` (`boolean`, default false): Forces the fallback (initials/icon) even while an image is loading.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl" | number`, default md): Token size, or a number for an exact px size (font-size scales ~0.4x; the status Badge maps to the nearest token bucket).
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color for the fallback background.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default full): Border radius.
- `colorDepth` (`50 | 100 | ... | 950`, default 500): Shade depth for the selected color.
- `isBordered` (`boolean`, default false): Adds a ring border around the avatar.
- `isDisabled` (`boolean`, default false): Dims the avatar and disables interaction.
- `isFocusable` (`boolean`, default false): Makes the avatar keyboard-focusable.
- `tooltip` (`ReactNode | boolean | (Omit<TooltipProps, "children"|"content"> & { content?: ReactNode })`, default false): Wraps the avatar in a Tooltip.
- `status` (`"online" | "offline" | "dnd"`): Status dot indicator.
- `ImgComponent` (`ElementType`, default "img"): Renders the image through a different component (e.g.
- `imgProps` (`ComponentPropsWithoutRef<ImgComponent>`): Extra props forwarded to the image element/component.
- `classNames` (`Partial<Record<AvatarSlot, string>>`): Per-slot class overrides (base/img/fallback/name/icon/status).
- `className` (`string`): Class applied to the root element.
- `AvatarGroup` (`{ max?, total?, size?, color?, radius?, isGrid?, isDisabled?, isBordered?, overlap?, renderCount?, classNames? }`): Stacks Avatar children and collapses whatever's past max (default 5) into a "+N" -- pass total instead of relying on children.length if you're not rendering ...

### Chip (`/components/chip`)
- `children` (`ReactNode`): Chip label content.
- `avatar` (`ReactNode`): Avatar rendered at the start of the chip.
- `startContent` (`ReactNode`): Content rendered before the label.
- `endContent` (`ReactNode`): Content rendered after the label, before the close button.
- `closeIcon` (`ReactNode`): Overrides the default × close icon.
- `variant` (`"solid" | "soft" | "bordered" | "dot"`, default solid): Visual style variant.
- `shadow` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg"`, default none): Box-shadow depth.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Chip size.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default full): Border radius.
- `colorDepth` (`50 | 100 | ... | 950`, default 500): Shade depth for the selected color.
- `isDisabled` (`boolean`, default false): Disables interaction.
- `selected` (`boolean`): Controlled selected state; renders as a toggleable role="button" chip.
- `defaultSelected` (`boolean`): Uncontrolled initial selected state.
- `onClose` (`(e: PressEvent) => void`): Shows a close button and is called when it's pressed.
- `onSelectedChange` (`(selected: boolean) => void`): Called when selected state changes.
- `classNames` (`Partial<Record<ChipSlot, string>>`): Per-slot class overrides (base/content/dot/avatar/closeButton/endContent).
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.

### Tooltip (`/components/tooltip`)
- `children` (`ReactNode`): The trigger element the tooltip attaches to.
- `content` (`ReactNode`): Tooltip content.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default md): Tooltip size.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Semantic color.
- `colorDepth` (`number`, default 100): Shade depth for the selected color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default md): Border radius.
- `shadow` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg"`, default sm): Box-shadow depth.
- `showArrow` (`boolean`, default false): Shows a pointing arrow.
- `triggerScaleOnOpen` (`boolean`, default false): Slightly scales the trigger while the tooltip is open.
- `placement` (`"top" | "bottom" | "left" | "right" | ... (12-way)`, default top): Position relative to the trigger.
- `offset` (`number`, default 7): Distance from the trigger.
- `containerPadding` (`number`, default 12): Minimum distance kept from the viewport edge.
- `crossOffset` (`number`, default 0): Offset along the cross axis.
- `shouldFlip` (`boolean`, default true): Flips placement to stay in the viewport.
- `portalContainer` (`Element | DocumentFragment | null`): Custom portal mount target.
- `updatePositionDeps` (`unknown[]`): Extra dependencies that make the tooltip re-measure its position, for example when its content changes size while open.
- `delay` (`number`, default 0): Open delay in ms.
- `closeDelay` (`number`, default 500): Close delay in ms (also floors touch-triggered opens).
- `isOpen` (`boolean`): Controlled open state.
- `defaultOpen` (`boolean`, default false): Uncontrolled initial open state.
- `isKeyboardDismissDisabled` (`boolean`, default false): Disables closing via Escape.
- `isDismissable` (`boolean`, default false): Allows dismissing an isOpen-controlled tooltip via outside click/Escape.
- `shouldCloseOnBlur` (`boolean`, default true): Closes when the trigger loses focus.
- `shouldCloseOnInteractOutside` (`(element: HTMLElement) => boolean`): Custom predicate for outside-interaction dismissal.
- `isDisabled` (`boolean`, default false): Disables the tooltip entirely.
- `disableAnimation` (`boolean`, default false): Disables the enter/exit animation.
- `onOpenChange` (`(isOpen: boolean) => void`): Called when open state changes.
- `onClose` (`() => void`): Called when the tooltip closes.
- `className` (`string`): Class applied to the tooltip content.
- `classNames` (`{ base?; content?; arrow? }`): Per-slot class overrides.

### Line Chart (`/components/chart-line`)
- `data` (`Row[] | { categories, series }`): Row-based data array, or explicit categories/series (required).
- `x` (`keyof Row | ((row: Row) => ChartCategory)`): Category accessor, row-mode only.
- `series` (`ChartSeriesDef<Row> | ChartSeriesDef<Row>[]`): Series accessor(s), row-mode only.
- `title / description` (`ReactNode`): Chart heading text.
- `ariaLabel` (`string`): Accessible label for the chart.
- `dataFormat` (`ChartDataFormatOptions`): Value formatting (prefix/suffix/decimals) for labels/tooltips.
- `showLabels` (`ChartShowLabelsOptions`): Inline value-label visibility.
- `type` (`"line" | "area" | "bar" | "column" | "pie" | "donut" | "heatmap" | "sparkline" | "combo"`): Chart type (required).
- `background` (`string`): Chart background color.
- `unstyled` (`boolean`, default false): Drop the built-in <figure> card frame (border / padding / radius / surface) — for a chart nested in a Card or a sparkline slot.
- `palette` (`{ colors?; colorShade?; roles? }`): Series color palette overrides.
- `line / bar / column / pieStyle / pie / heatmap` (`type-specific options`): Per-type rendering options.
- `axisY2` (`ChartAxisOptions`): type="combo": the right-hand value axis (show, tickCount, title) for series with axis: "right".
- `sparkline` (`{ kind?: "line" | "area" | "column" }`, default { kind: "line" }): type="sparkline" only: the shape of the small trend.
- `referenceLines` (`{ value, label?, color?, dashed? }[]`): Lines across a line, area, column or bar chart at fixed values (a target, a limit).
- `dataTable` (`boolean`, default true): Adds a visually hidden table of the values, so a screen reader can read the numbers.
- `labels` (`Partial<ChartLabels>`, default English): Translate or reword every text the chart adds: export, fullscreen, resetZoom, loading, noData, keyboardHint, filterAll, total and the data table headings.
- `height` (`number`, default 320): Chart height in pixels.
- `padding` (`{ top?; right?; bottom?; left?: number }`): Plot area padding.
- `axis / axisX / axisY` (`ChartAxisOptions`): Axis visibility, ticks, title (drawn under the axis) and, on axisX, scale (auto, category or time).
- `grid` (`ChartGridOptions`): Gridline configuration.
- `legend` (`boolean | ChartLegendOptions`, default true for multi-series): Legend visibility/position.
- `tooltip` (`boolean | ChartTooltipOptions`, default true): Hover/focus tooltip visibility and formatting.
- `zoom` (`false | { mode?: "x" | "xy"; wheel?; pan? }`): Enables zoom/pan on axis charts.
- `export` (`false | { formats?: ("svg" | "png")[]; filename? }`): Enables an export action (SVG/PNG).
- `fullscreen` (`false | { enabled?: boolean }`): Enables a fullscreen toggle action.
- `filters` (`false | ChartFiltersOptions<Row>`): Enables interactive data filters.
- `isLoading` (`boolean`): Shows a loading state instead of the chart.
- `error` (`ReactNode`): Shows an error state instead of the chart.
- `empty` (`ReactNode`): Shown when data resolves to nothing plottable.
- `onPointClick` (`(event: ChartPointEvent<Row>) => void`): Called when a data point is clicked or activated via keyboard.
- `onCellClick` (`(event: ChartHeatmapCellEvent<Row>) => void`): type="heatmap" — a cell was clicked or keyboard-activated.
- `onLegendChange` (`(hiddenSeriesIds: string[]) => void`): Called when series visibility toggles via the legend.
- `onSelectionChange` (`(selection: ChartSelection) => void`): Called when a zoom/brush selection changes.
- `className / classNames / style` (`string / ChartClassNames / CSSProperties`): Styling overrides (classNames covers base/header/title/description/actions/stage/svg/legend/filters).

### Divider (`/components/divider`)
- `children` (`ReactNode`): Optional inline label; renders the line in two segments around it.
- `orientation` (`"horizontal" | "vertical"`, default horizontal): Line direction.
- `variant` (`"fullWidth" | "inset" | "middle"`, default fullWidth): Inset behavior at the line's ends.
- `lineStyle` (`"solid" | "dashed" | "dotted"`, default solid): Line style.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default default): Line color.
- `colorDepth` (`50 | 100 | ... | 950`, default 300): Shade depth for the selected color.
- `thickness` (`number | string`): Line thickness override.
- `labelPlacement` (`"start" | "center" | "end"`, default center): Where a label renders along the line, when children are provided.
- `className` (`string`): Class applied to the root element.

### Backdrop (`/components/backdrop`)
- `children` (`ReactNode`): Content rendered above the backdrop.
- `blur` (`boolean | "sm" | "md" | "lg" | number`, default true (8px)): Backdrop blur amount.
- `backgroundColor` (`string`, default "var(--oks-palette-neutral-950, #000)"): Backdrop tint color.
- `backgroundOpacity` (`number`, default 80): Backdrop opacity (0-100).
- `zIndex` (`number`): Explicit stacking z-index; auto-computed per overlay depth when unset.
- `portal` (`boolean`, default true): Renders through a React portal.
- `container` (`Element | DocumentFragment | null`): Custom portal mount target.
- `contentFullSize` (`boolean`, default false): Stretches the content wrapper to fill the backdrop.
- `isOpen` (`boolean`): Controls whether the backdrop is open (required).
- `closeOnOutsideClick` (`boolean`, default true): Closes when clicking outside the content.
- `closeOnEscape` (`boolean`, default true): Closes on Escape.
- `lockScroll` (`boolean`, default true): Locks body scroll while open.
- `trapFocus` (`boolean`, default true): Traps keyboard focus within the content while open.
- `animationDuration` (`number`, default 0.3): Enter/exit animation duration in seconds.
- `animationType` (`"fade" | "zoom" | "slideUp" | "slideDown" | "slideLeft" | "slideRight"`, default fade): Entrance/exit animation.
- `easing` (`"ease" | "easeIn" | "easeOut" | "easeInOut"`, default ease): Animation easing curve.
- `onClose` (`() => void`): Called to close the backdrop (required).
- `className` (`string`): Class applied to the backdrop layer.
- `style` (`CSSProperties`): Inline styles for the backdrop layer.
- `contentClassName` (`string`): Class applied to the content wrapper.
- `contentStyle` (`CSSProperties`): Inline styles for the content wrapper.

### PageTitle (`/components/page-title`)
- `title` (`ReactNode`, default "Title"): Heading text/content.
- `icon` (`ReactNode`): Icon rendered beside the title.
- `subtitle` (`ReactNode`): Secondary text rendered below the title.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | "black" | "white" | string`): Text color; inherits currentColor when unset.
- `colorDepth` (`number`, default 500): Shade depth for the selected color.
- `iconPosition` (`"start" | "end"`, default start): Icon placement relative to the title.
- `as` (`"h1" | "h2" | "h3" | "h4" | "h5" | "h6"`, default "h4"): Semantic heading element rendered.
- `tooltip` (`ReactNode | boolean | (Omit<TooltipProps, "children"|"content"> & { content?: ReactNode })`): Wraps the title in a Tooltip.
- `onKeyDown` (`(e: KeyboardEvent<HTMLDivElement>) => void`): Keydown handler on the root element.
- `className` (`string`): Class applied to the root element.
- `classNames` (`Partial<Record<PageTitleSlot, string>>`): Per-slot class overrides (base/title/icon/subtitle).
- `style` (`CSSProperties`): Inline styles for the root element.

### Card (`/components/card`)
- `children` (`ReactNode`): Card content — usually CardHeader / CardBody / CardFooter.
- `shadow` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg"`, default xs): Elevation.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default lg): Corner radius.
- `isBlurred` (`boolean`, default false): Translucent background + backdrop blur where supported.
- `isHoverable` (`boolean`, default false): Lift on hover without becoming a control.
- `isPressable` (`boolean`, default false): Whole card is one activatable control; fires onPress on click / Enter / Space.
- `isDisabled` (`boolean`, default false): Dim the card and block onPress.
- `fullWidth` (`boolean`, default false): width: 100%.
- `as` (`ElementType`, default div): Render as a different element/component (e.g.
- `onPress` (`(e) => void`): Called when isPressable and the card is activated.
- `classNames` (`{ base?: string }`): Slot class overrides.
- `CardHeader / CardBody / CardFooter` (`div props`): Padded regions inside a Card.

### Stat (`/components/stat`)
- `label` (`ReactNode`): Required.
- `value` (`ReactNode`): Required.
- `delta` (`ReactNode`): Change indicator — shown as a coloured pill.
- `trend` (`"up" | "down" | "flat"`): Colour + arrow for delta.
- `icon` (`ReactNode`): In a rounded tile, top-right.
- `spark` (`ReactNode`): A sparkline — pair with <Chart unstyled … />.
- `help` (`ReactNode`): Small helper line under the value.
- `size` (`"sm" | "md" | "lg"`, default md): Value size.
- `StatGroup columns` (`number`, default 4): Responsive grid — collapses to 2 / 1 columns.

### Timeline (`/components/timeline`)
- `Timeline children` (`TimelineItem[]`): Renders as an <ol>.
- `TimelineItem.title` (`ReactNode`): Shown at the top of the content.
- `TimelineItem.time` (`ReactNode`): Right-aligned timestamp.
- `TimelineItem.icon` (`ReactNode`): Rendered in the marker (replaces the dot).
- `TimelineItem.color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default default): Marker colour.
- `TimelineItem.children` (`ReactNode`): Body text.

### Calendar (`/components/calendar`)
- `selectionMode` (`"single" | "range"`, default single): Single-date or start/end range selection.
- `value / defaultValue` (`string | null · { start, end } | null`): Controlled / initial selection.
- `onChange` (`(value) => void`): Fires with null when a single selection is toggled off.
- `month / defaultMonth` (`string | Date`, default selection, else today): Displayed month.
- `onMonthChange` (`(month: Date) => void`): Fired when the visible month changes.
- `minValue / maxValue` (`string | Date`): Days outside the bound are disabled.
- `isDateUnavailable` (`(date: Date) => boolean`): Per-day disable predicate.
- `weekStartsOn` (`0 | 1`, default 0): Sunday or Monday.
- `showOutsideDays` (`boolean`, default true): Render leading/trailing days of adjacent months.
- `fixedWeeks` (`boolean`, default false): Always 6 rows so height doesn't jump between months.
- `renderDay` (`(ctx) => ReactNode`, default day number): Custom day content.
- `isDisabled` (`boolean`, default false): Disable the whole calendar.
- `size` (`"sm" | "md" | "lg"`, default md): Cell size.
- `ariaLabel` (`string`, default month name): Accessible label for the grid.
- `classNames` (`{ base?, header?, heading?, nav?, navButton?, grid?, weekday?, week?, day? }`): Slot classes.

### SplitLayout (`/components/split-layout`)
- `direction` (`"horizontal" | "vertical"`, default horizontal): Arrange panes as columns or rows.
- `sizes` (`Array<number | null>`): Controlled pane sizes in px (null for the flex pane).
- `onResize` (`(sizes) => void`): Fires on drag, keyboard resize, or collapse.
- `keyboardStep` (`number`, default 24): px moved per arrow-key press on a handle.
- `classNames` (`{ base?, pane?, handle? }`): Slot classes.
- `aria-label` (`string`): Names the group.
- `defaultSize` (`number | string`): Initial size — px or a CSS length ("32%").
- `minSize / maxSize` (`number`, default 80 / —): px clamp while resizing.
- `isResizable` (`boolean`, default false): Show a drag handle on this pane's trailing edge.
- `isCollapsible` (`boolean`, default false): Collapse when dragged past ~60% of minSize, or on Enter/Space on the handle.
- `collapsedSize` (`number`, default 0): Size when collapsed.
- `isCollapsed / defaultCollapsed / onCollapsedChange` (`—`): Controlled / uncontrolled collapse.
- `label` (`string`): Accessible name for this pane's handle ("Resize <label>").

### Message (`/components/message`)
- `author` (`ReactNode`): Sender name.
- `avatar` (`ReactNode`): e.g.
- `timestamp` (`ReactNode`): Shown by the author, or under the bubble on a continuation.
- `align` (`"start" | "end"`, default start): "end" right-aligns — use for the current user.
- `variant` (`"bubble" | "plain"`, default bubble): Speech bubble or flat row (system notices).
- `color` (`"default" | "primary" | "neutral" | "success" | "warning" | "danger"`, default default): Bubble tint.
- `isContinuation` (`boolean`, default false): Same author as the previous message — drops the avatar/author line, tightens spacing.
- `status` (`"sending" | "sent" | "delivered" | "read" | "failed"`): Delivery indicator under an align=end message.
- `header / footer` (`ReactNode`): Reply-to quote / reactions / attachments.
- `classNames` (`{ base?, avatar?, meta?, author?, timestamp?, body?, footer?, status? }`): Slot classes.
- `isLive` (`boolean`, default true): role="log" + aria-live="polite" so appended messages are announced.
- `header` (`ReactNode`): Pinned above the messages (a "load earlier" button, a date divider).
- `classNames` (`{ base?, inner? }`): Slot classes.

### Board (`/components/board`)
- `columns` (`BoardColumnData[]`): { id, title, limit?, isDropDisabled?, color?, headerActions?, footer?
- `items` (`Item[]`): Flat list, grouped by column at render.
- `getItemId` (`(item) => string`): Stable id.
- `getItemColumn` (`(item) => string`): Which column the item is in.
- `renderCard` (`(item, ctx) => ReactNode`): ctx: { isDragging, isGrabbed, column, index }.
- `onItemMove` (`(move) => void`): move: { item, itemId, from: {columnId,index}, to: {columnId,index} }.
- `isDragDisabled` (`boolean`, default false): Read-only board — no dragging.
- `renderColumnHeader` (`(column, { count }) => ReactNode`): Replace the default title + count pill.
- `emptyColumnContent` (`ReactNode`): Shown in a column with no cards.
- `columnWidth` (`number`, default 288): Column width in px.
- `isCompact` (`boolean`, default false): Tighter spacing.
- `classNames` (`{ base?, column?, columnHeader?, columnTitle?, columnCount?, list?, card?, footer? }`): Slot classes.
- `aria-label` (`string`): Required — names the board.

### Skeleton (`/components/skeleton`)
- `variant` (`"text" | "rect" | "circle"`, default rect): Shape of a standalone placeholder.
- `width` (`number | string`): CSS length (number → px).
- `height` (`number | string`): CSS length (number → px).
- `radius` (`OksRadius`): Corner radius override.
- `lines` (`number`): variant="text" only — stacked lines, last one shorter.
- `isLoaded` (`boolean`, default false): Wrapper mode — reveal children when true.
- `children` (`ReactNode`): Wrapper-mode content, hidden behind the placeholder until isLoaded.
- `classNames` (`{ base?: string }`): Slot class overrides.

### Table (`/components/table`)
- `columns` (`TableColumn<Row>[]`): { key, header, align?, sortable?, sortValue?, render?, width?, headerClassName?, cellClassName?
- `rows` (`Row[]`): The data.
- `getRowKey` (`(row, index) => string | number`): Stable key — use an id field, not the index.
- `aria-label` (`string`): Required.
- `sortDescriptor / defaultSortDescriptor` (`{ column, direction } | null`, default null): Current / initial sort.
- `onSortChange` (`(descriptor) => void`): Present → server-side sort; omit for client-side.
- `selectionMode` (`"none" | "single" | "multiple"`, default none): Row selection.
- `selectedKeys / defaultSelectedKeys / onSelectionChange` (`Iterable<Key> / …`): Controlled / uncontrolled selection.
- `isRowSelectable` (`(row) => boolean`): Disable selection per row.
- `renderExpandedRow` (`(row) => ReactNode`): Adds the chevron expand-toggle column.
- `expandedKeys / defaultExpandedKeys / onExpandedChange` (`Iterable<Key> / …`): Controlled expansion.
- `isLoading / loadingRowCount` (`boolean / number`, default false / 5): Skeleton rows while loading.
- `emptyContent` (`ReactNode`, default <EmptyState title="No data" />): Shown when rows is empty.
- `onRowAction` (`(key, row) => void`): Makes rows clickable (click / Enter / Space).
- `stickyHeader / maxHeight` (`boolean / number | string`, default false / —): Sticky header + vertical scroll container.
- `isCompact / isStriped / removeWrapper` (`boolean`, default false): Density and framing.
- `topContent / bottomContent` (`ReactNode`): Toolbar / pagination slots.
- `classNames` (`TableClassNames`): Per-slot class overrides.

### EmptyState (`/components/empty-state`)
- `title` (`ReactNode`): Required.
- `description` (`ReactNode`): Supporting sentence.
- `icon` (`ReactNode`): Rendered in a tinted circular tile.
- `actions` (`ReactNode`): Buttons / links below the description.
- `size` (`"sm" | "md" | "lg"`, default md): Padding + icon + title scale.
- `classNames` (`{ base?, icon?, title?, description?, actions? }`): Slot class overrides.

### Progress (`/components/progress`)
- `value` (`number`): Current value.
- `minValue / maxValue` (`number`, default 0 / 100): Range.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default primary): Semantic colour of the indicator.
- `size` (`"sm" | "md" | "lg"`, default md): Bar / ring size.
- `label` (`ReactNode`): Text label (also becomes the aria-label when a string).
- `showValueLabel` (`boolean`, default false): Render the formatted value.
- `formatValue` (`(value, maxValue) => ReactNode`, default percentage): Value-label formatter.
- `radius` (`string`): Progress only — track radius.
- `strokeWidth` (`number`, default 4): CircularProgress only — ring thickness.

### Rating (`/components/rating`)
- `value / defaultValue` (`number`, default 0): The rating, 0 (none) to max.
- `onChange` (`(value: number) => void`): Called with the new rating (0 when cleared).
- `max` (`number`, default 5): How many icons, 1 to 10.
- `precision` (`1 | 0.5`, default 1): Whole or half steps.
- `size` (`"sm" | "md" | "lg"`, default md): Icon size (18, 24 and 32 px).
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default warning): Colour of the filled icons.
- `icon / emptyIcon` (`ReactNode`, default a star): The filled and the empty icon.
- `isReadOnly` (`boolean`, default false): Shows the rating; announced as an image.
- `isDisabled` (`boolean`, default false): Dimmed, not focusable, ignores input.
- `allowClear` (`boolean`, default false): Choosing the current rating again clears it; Delete, Backspace and 0 clear from the keyboard.
- `showValue` (`boolean`, default false): Shows the number beside the icons.
- `getValueText` (`(value, max) => string`, default "4 out of 5"): The spoken value; use it to translate.
- `onHoverChange` (`(value: number | null) => void`): The rating under a mouse pointer (a touch has no hover), null when it leaves.
- `label / description` (`ReactNode`): A visible label (it names the control) and help text.
- `error` (`ReactNode | boolean`, default form's error for name): An error message, or true for the invalid look.
- `name` (`string`): In a Form: the key it is stored under (null for no rating, so required means has a rating).
- `validation` (`FieldValidation`): Rules when inside a Form.
- `classNames` (`Partial<Record<slot, string>>`): Class per part: base, label, control, star, icon, valueText, description, error.
- `aria-label` (`string`): Needed when there is no label.

### TreeView (`/components/tree-view`)
- `nodes` (`TreeNode[]`): The tree: { key, label, children?, hasChildren?, icon?, isDisabled?, textValue?, data?
- `selectionMode` (`"none" | "single" | "multiple"`, default single): What a click selects.
- `selectedKeys / defaultSelectedKeys` (`Iterable<string>`): Selection, controlled or not.
- `onSelectionChange` (`(keys: string[]) => void`): Called when the selection changes.
- `expandedKeys / defaultExpandedKeys` (`Iterable<string>`): Which branches are open.
- `onExpandedChange` (`(keys: string[]) => void`): Called when a branch opens or closes.
- `isCheckable` (`boolean`, default false): Adds a check mark to every row.
- `checkedKeys / defaultCheckedKeys` (`Iterable<string>`): Checked rows.
- `onCheckedChange` (`(keys: string[]) => void`): Reports every fully checked node, parents included.
- `expandOnClick` (`boolean`, default false): Clicking a branch row opens it as well as selecting it.
- `onAction` (`(node: TreeNode) => void`): Enter or a double click.
- `loadChildren` (`(node) => Promise<TreeNode[]>`): Called the first time a node with hasChildren and no children opens.
- `onLoadError` (`(node, error) => void`): Loading failed: the branch closes again, opening it retries.
- `renderLabel` (`(node, state) => ReactNode`): Draw a row's label yourself.
- `size` (`"sm" | "md" | "lg"`, default md): Row height and text size.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default primary): Selected row, focus ring and check marks.
- `indent` (`number`, default 20): Pixels each level moves in.
- `isDisabled` (`boolean`, default false): The whole tree.
- `emptyContent` (`ReactNode`): Shown when nodes is empty.
- `onMove` (`(move: TreeMove) => void`): Lets rows be dragged before, after or into another row, or moved with Alt and the arrow keys.
- `canMove` (`(node: TreeNode) => boolean`, default every enabled row): Which rows can be picked up (with onMove).
- `canDrop` (`(move: TreeMove) => boolean`, default every move): Whether a move is allowed (with onMove).
- `labels` (`Partial<TreeViewLabels>`, default English): loading, loadFailed(name), and with onMove: moveHint, moved, cannotMove.
- `classNames` (`Partial<Record<slot, string>>`): Class per part: base, item, toggle, checkbox, icon, label, empty.
- `aria-label / aria-labelledby` (`string`): One is needed: it names the tree.

### DiffView (`/components/diff-view`)
- `before / after` (`string`): The older and the newer text.
- `mode` (`"split" | "unified"`, default split): Side by side, or one column with removed lines above added ones.
- `context` (`number`, default 3): Unchanged lines shown around each change.
- `showLineNumbers` (`boolean`, default true): The line-number columns.
- `wordDiff` (`boolean`, default true): Highlights the changed words inside a replaced line.
- `ignoreWhitespace` (`boolean`, default false): Lines that differ only in spaces and tabs count as unchanged.
- `wrapLines` (`boolean`, default true): Wraps long lines.
- `monospace` (`boolean`, default true): A fixed-width font, for code.
- `showSummary` (`boolean`, default true): The line above the table (2 lines added, 1 removed).
- `beforeTitle / afterTitle` (`ReactNode`, default Before / After): Column titles, such as a revision name or a date.
- `labels` (`Partial<DiffViewLabels>`, default English): The text DiffView adds: removed, added, showUnchanged(count), summary(added, removed), noChanges, before, after.
- `classNames` (`Partial<Record<slot, string>>`): Class per part: base, summary, table, row, lineNumber, content, fold.

### ColorPicker (`/components/color-picker`)
- `value / defaultValue` (`string`, default ""): The colour as #2563eb, rgb(…) or hsl(…).
- `onChange` (`(value: string) => void`): Every change, written in format.
- `onChangeEnd` (`(value: string) => void`): ColorPicker only.
- `format` (`"hex" | "rgb" | "hsl"`, default hex): How the value is written.
- `showAlpha` (`boolean`, default false): Adds a transparency slider.
- `swatches` (`Array<string | { value, label? }>`): Colours to pick with one click.
- `showInput` (`boolean`, default true): The text box with the value.
- `showEyeDropper` (`boolean`, default true): A button that picks a colour from the screen, where the browser supports it (Chrome and Edge).
- `isDisabled` (`boolean`, default false): Dimmed and not interactive.
- `label / description` (`ReactNode`): ColorField only.
- `error` (`ReactNode | boolean`, default form's error for name): ColorField only.
- `name / validation` (`string / FieldValidation`): ColorField only.
- `size / isReadOnly / placeholder` (`sm | md | lg / boolean / string`, default md / false / —): ColorField only.
- `labels` (`Partial<ColorPickerLabels>`, default English): area, saturation, brightness, hue, alpha, value, eyeDropper, swatches, open, dialog.
- `classNames` (`Partial<Record<slot, string>>`): Class per part (ColorPicker: base, area, thumb, hue, alpha, preview, input, swatches, swatch; ColorField: base, label, control, swatch, input, popover, descr...

### CodeField (`/components/code-field`)
- `value / defaultValue` (`string`, default ""): The text.
- `onChange` (`(value: string) => void`): Every change.
- `language` (`string`, default plaintext): Highlighting: css, json, javascript, typescript, html, markdown, yaml, python, sql, bash and the other languages the TextEditor code block knows.
- `label / description` (`ReactNode`): A visible label (it names the field) and help text.
- `error` (`ReactNode | boolean`, default form's error for name): An error message, or true for the invalid look.
- `name` (`string`): In a Form: the key the text is stored under.
- `validation` (`FieldValidation`): Rules when inside a Form.
- `showLineNumbers` (`boolean`, default true): The line-number gutter.
- `minRows / maxRows` (`number`, default 4 / 20): The field grows with its text between these heights, in lines, then scrolls.
- `tabSize` (`number`, default 2): Spaces per indent.
- `checkJson` (`boolean`, default true): With language="json", shows where the text stops being valid while typing.
- `isReadOnly` (`boolean`, default false): Read-only keeps the text selectable but not editable.
- `isDisabled` (`boolean`, default false): Dims the field and ignores input.
- `size` (`"sm" | "md"`, default md): Font size and padding.
- `labels` (`Partial<CodeFieldLabels>`, default English): tabHint and invalidJson(line, column).
- `classNames` (`Partial<Record<slot, string>>`): Class per part: base, label, control, gutter, input, description, error.

### Sortable (`/components/sortable`)
- `items` (`T[]`): The items, in their current order.
- `getKey` (`(item: T) => string`): A unique, stable key for an item.
- `getLabel` (`(item: T) => string`, default the key): The item's name, read when it is picked up and moved.
- `renderItem` (`(item: T, state) => ReactNode`): Draws an item.
- `onReorder` (`(items: T[], move: { key, from, to }) => void`): Called once per drop with the items in their new order and the 0-based old and new positions.
- `layout` (`"vertical" | "horizontal" | "grid"`, default vertical): How the items flow.
- `dragFromItem` (`boolean`, default false): A pointer can drag from anywhere on an item, not only its handle.
- `isDisabled` (`boolean`, default false): Nothing can be moved.
- `labels` (`Partial<SortableLabels>`, default English): handle(name), hint, pickedUp, movedTo, dropped, cancelled.
- `classNames` (`Partial<Record<slot, string>>`): Class per part: base, item, handle, content.
- `aria-label` (`string`): Names the list.

### DropZone (`/components/drop-zone`)
- `data` (`unknown`): Draggable.
- `label` (`string`): Draggable: its name, read by screen readers and shown next to the pointer.
- `accepts` (`(data: unknown) => boolean`, default anything): DropZone.
- `onDrop` (`(data: unknown) => void`): DropZone.
- `onDropFiles` (`(files: File[]) => void`): DropZone.
- `accept` (`string`): DropZone.
- `children` (`ReactNode`, default label): Draggable: what it looks like.
- `isDisabled` (`boolean`, default false): A disabled Draggable cannot be picked up; a disabled DropZone takes nothing.
- `labels` (`Partial<DropZoneLabels>`, default English): roleDescription, hint, pickedUp, dropHere(zone), dropped, cancelled.

### MediaLibrary (`/components/media-library`)
- `items` (`MediaItem[]`): { id, name, thumbnail?, type?, size?, description?, data?
- `selectionMode` (`"single" | "multiple"`, default single): Pick one item or many.
- `selectedKeys / defaultSelectedKeys / onSelectionChange` (`string[] / (keys: string[]) => void`, default []): The picked item ids, controlled or not.
- `onAction` (`(item: MediaItem) => void`): Enter or a double click on an item (use this one).
- `filtering` (`"local" | "none"`, default local): local: the library filters items by search and type.
- `search / defaultSearch / onSearchChange` (`string / (query) => void`, default ""): The search text.
- `kinds` (`MediaKind[]`, default every kind): Type filters offered after All: image, video, audio, document.
- `filter / defaultFilter / onFilterChange` (`"all" | MediaKind`, default all): The chosen type filter.
- `hasMore / onLoadMore / isLoading` (`boolean / () => void / boolean`): Shows Load more and calls onLoadMore when it is clicked or scrolls into view.
- `onUpload` (`(files: File[]) => void`): Adds an Upload button and lets files be dropped on the library.
- `accept` (`string`): File types for uploads, like an input's accept.
- `emptyContent` (`ReactNode`, default No media yet): Shown when there are no items at all.
- `size` (`"sm" | "md" | "lg"`, default md): Thumbnail size.
- `labels` (`Partial<MediaLibraryLabels>`, default English): library, search, filters, kinds, upload, dropFiles, loadMore, loading, empty, noResults(query), selected(count), clearSelection.
- `classNames` (`Partial<Record<slot, string>>`): Class per part: base, toolbar, search, filters, grid, item, thumbnail, name, footer.

### Accordion (`/components/accordion`)
- `selectionMode` (`"single" | "multiple"`, default multiple): One-open accordion vs many.
- `variant` (`"light" | "bordered" | "splitted"`, default light): Dividers / one box / separate cards.
- `isCompact` (`boolean`, default false): Tighter padding.
- `expandedKeys / defaultExpandedKeys / onExpandedChange` (`Iterable<string> / …`): Controlled / uncontrolled (identity = the AccordionItem key).
- `classNames` (`{ base?, item?, trigger?, content? }`): Slot class overrides.
- `title / subtitle / startContent` (`ReactNode`): Header content.
- `isDisabled` (`boolean`, default false): Non-togglable.
- `itemKey` (`string`, default the React key): Explicit identity if you can't set key.

### Nav (`/components/nav`)
- `items` (`NavItemData[]`): { key, label, href?, icon?, badge?, children?, isDisabled?, isSection?
- `aria-label` (`string`): Required.
- `selectedKey` (`string`): Which leaf is the current page.
- `isItemActive` (`(item) => boolean`): Custom active check (wins over selectedKey).
- `onItemSelect` (`(item) => void`): Fired on leaf / link activation.
- `expandedKeys / defaultExpandedKeys / onExpandedChange` (`Iterable<string> / …`): Controlled / uncontrolled expansion (active-leaf ancestors auto-expand).
- `expansionMode` (`"single" | "multiple"`, default multiple): "single" = accordion per section.
- `isCollapsed` (`boolean`, default false): Icon rail + hover/focus flyouts for groups.
- `renderItem` (`(args) => ReactNode`): Full control over each row — for router NavLink, etc.
- `classNames` (`{ base?, list?, item?, link?, sectionTitle? }`): Slot class overrides.

### Breadcrumbs (`/components/breadcrumbs`)
- `separator` (`ReactNode`, default chevron): Rendered between items.
- `maxItems` (`number`): Collapse the middle into a clickable … once exceeded.
- `itemsBeforeCollapse` (`number`, default 1): Leading items kept when collapsed.
- `itemsAfterCollapse` (`number`, default 2): Trailing items kept when collapsed.
- `classNames` (`{ base?, list?, item?, separator? }`): Slot class overrides.
- `href` (`string`): Renders an <a>.
- `isCurrent` (`boolean`, default last item): Render as current-page text with aria-current.
- `as` (`ElementType`, default "a" / "span"): Render the link as another component (router Link).

### Pagination (`/components/pagination`)
- `pageCount` (`number`): Total pages.
- `total / pageSize` (`number`, default — / 10): Item count → derives pageCount.
- `page / defaultPage` (`number`, default — / 1): Controlled / initial page (1-based).
- `onChange` (`(page: number) => void`): Fired on any page change.
- `siblingCount` (`number`, default 1): Pages shown either side of the current one.
- `boundaryCount` (`number`, default 1): Pages always shown at each end.
- `showEdges` (`boolean`, default false): First / last jump buttons.
- `hideNavigation` (`boolean`, default false): Hide the prev / next arrows.
- `size` (`"sm" | "md" | "lg"`, default md): Control size.
- `variant` (`"solid" | "soft" | "bordered" | "ghost"`, default solid): Styles the selected page.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"`, default primary): Selected-page color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default md): Corner rounding of each page button.
- `isDisabled` (`boolean`, default false): Disable every button.
- `getItemAriaLabel` (`(type, page, isSelected) => string`): Localise the button labels.
- `classNames` (`{ base?, list?, item?, page?, prev?, next?, ellipsis? }`): Slot classes.
- `PaginationSummary` (`{ page, pageSize, total, format? }`): Renders "Showing X–Y of Z"; format(from, to, total) overrides the text.

### SegmentedControl (`/components/segmented-control`)
- `options` (`{ label, value, icon?, isDisabled? }[]`): The segments.
- `value / defaultValue` (`string`, default first option): Controlled / initial selection.
- `onChange` (`(value) => void`): Fired on selection.
- `size` (`"sm" | "md" | "lg"`, default md): Control size.
- `fullWidth` (`boolean`, default false): Stretch to fill the container, equal segments.
- `isDisabled` (`boolean`, default false): Disable the whole control.
- `classNames` (`{ base?, thumb?, option? }`): Slot classes.

### CommandPalette (`/components/command-palette`)
- `isOpen` (`boolean`): Whether the palette is shown.
- `onClose` (`() => void`): Fired on Escape, outside click, and after a selection.
- `items` (`CommandPaletteItem[]`): The commands and destinations.
- `onSelect` (`(item) => void`): Fired on activation, after the item's own onSelect.
- `filter` (`(items, query) => items`, default built-in fuzzy): Replace the matcher; return the items to show, already ordered.
- `isLoading` (`boolean`, default false): Spinner in the input; suppresses the empty message.
- `query / defaultQuery` (`string`, default ""): Controlled / initial query.
- `onQueryChange` (`(query) => void`): Fired as the query changes.
- `emptyQueryItems` (`CommandPaletteItem[]`, default all items): List shown while the query is empty (recent / suggested).
- `placeholder` (`string`, default "Type a command or search…"): Input placeholder.
- `emptyMessage` (`ReactNode`, default "No results"): Shown when nothing matches.
- `footer` (`ReactNode`): Content below the list.
- `size` (`"sm" | "md" | "lg"`, default md): Palette width (480 / 600 / 720).
- `ariaLabel` (`string`, default "Command palette"): Accessible name for the dialog and listbox.
- `classNames` (`{ base?, header?, input?, list?, group?, item?, … }`): Slot classes.
- `closeOnEscape / closeOnOutsideClick / portal / container / zIndex / blur` (`—`): Passed through to Backdrop.
- `hotkey` (`"mod+k" | string | false`, default "mod+k"): Global open/toggle shortcut.
- `defaultOpen` (`boolean`, default false): Initial open state.
- `onOpenChange` (`(open) => void`): Fired when the open state changes.

### Text Field (`/components/form-field-text`)
- `type` (`"text" | "number" | "url" | "search" | "color" | "email"`, default "text"): Native input type -- all six render through TextField.
- `onChange` (`(value: string) => void`): Called with the input's resolved string value, not a raw ChangeEvent.
- `placeholder` (`string`): Placeholder text.
- `startIcon` (`ReactNode`): Leading icon.
- `endIcon` (`ReactNode`): Trailing icon.
- `prefix` (`ReactNode`): Leading affix (text or custom JSX).
- `suffix` (`ReactNode`): Trailing affix (text or custom JSX).
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Textarea Field (`/components/form-field-textarea`)
- `onChange` (`(value: string) => void`): Called with the textarea's resolved string value.
- `placeholder` (`string`): Placeholder text.
- `rows` (`number`, default 4): Visible line count.
- `showLengthCounter` (`boolean`, default false): Shows a character counter (uses maxLength when present).
- `maxLength` (`number`): Max character count, native textarea attribute.
- `startIcon / endIcon` (`ReactNode`): Leading/trailing icon.
- `prefix / suffix` (`ReactNode`): Leading/trailing affix.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Select Field (`/components/form-field-select`)
- `options` (`Array<{ label: ReactNode; value: string; disabled?; textValue?; startContent?; endContent? }>`, default []): Items in the menu.
- `onChange` (`(value: string | string[]) => void`): Called with the resolved value (array when multiple).
- `multiple` (`boolean`, default false): Enables multi-select (value becomes string[]).
- `native` (`boolean`, default false): Uses a native <select> instead of the custom popover.
- `placeholderOption` (`ReactNode`, default "Select…"): Placeholder row shown when value is empty (single select).
- `renderOption / renderValue / renderChip` (`(…) => ReactNode`): Custom option / selected-value / chip rendering.
- `startIcon / endIcon` (`ReactNode`): Leading/trailing icon on the trigger.
- `prefix / suffix` (`ReactNode`): Leading/trailing affix on the trigger.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Password Field (`/components/form-field-password`)
- `onChange` (`(value: string) => void`): Called with the input's resolved string value.
- `revealToggle` (`boolean`, default true): Shows the "eye" reveal toggle.
- `strongPassword` (`{ minLength?; minUpper?; minLower?; minNumber?; minSpecial? }`): Enables a live requirements checklist while focused.
- `placeholder` (`string`): Placeholder text.
- `startIcon / endIcon` (`ReactNode`): Leading icon / trailing icon (in addition to the reveal toggle).
- `prefix / suffix` (`ReactNode`): Leading/trailing affix.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### OTP Field (`/components/form-field-otp`)
- `ui` (`"segmented" | "single"`, default "segmented"): Segmented (N boxes) or a single text input with maxLength.
- `length` (`number`, default 6): Code length, clamped to 3..8.
- `format` (`"digits" | "alphanumeric"`, default "digits"): Allowed character set.
- `onChange` (`(value: string) => void`): Called with the resolved code string.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Phone Field (`/components/form-field-phone`)
- `value / defaultValue` (`{ code: string; phone: string }`): Controlled / uncontrolled value.
- `onChange` (`(value: { code; phone }) => void`): Called with the resolved value.
- `defaultCountryCode` (`string`, default "+1"): Fallback calling code.
- `countryCodeMode` (`"select" | "hidden"`, default "select"): Show or hide the calling-code UI.
- `countryOptions` (`Array<{ code; name?; label?; flag?; shortCode?; key? }>`, default built-in list): Override the available countries.
- `numbersOnly` (`boolean`, default true): Strips non-digits from the phone portion.
- `placeholder` (`string`): Placeholder for the phone input (phonePlaceholder is a legacy alias).
- `countryCodeAriaLabel` (`string`, default "Country code"): Accessible label for the country code select.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Range Field (`/components/form-field-range`)
- `selection` (`"single" | "range"`, default "single"): Single-thumb slider or dual-thumb range selection.
- `min / max` (`number | string`, default 0 / 100): Slider bounds.
- `step` (`number | string`): Step increment.
- `value / defaultValue` (`number (single) | { min; max } (range)`, default derived from min/max): Controlled / uncontrolled value.
- `onChange` (`(next) => void`): Called with the next value.
- `showValue` (`boolean`, default true): Shows the current value next to the slider.
- `formatValue` (`(value: number) => ReactNode`): Custom value formatting.
- `marks` (`number[]`): Tick marks along the rail.
- `startIcon / endIcon / prefix / suffix` (`ReactNode`): Adornments beside the slider.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### File Field (`/components/form-field-file`)
- `onChange` (`(files: File[]) => void`): Called with the resolved list of selected files.
- `accept` (`string`): Native file-type filter.
- `multiple` (`boolean`, default false): Allows selecting more than one file.
- `ui` (`"inline" | "dropzone"`, default "inline"): UI layout.
- `isDroppable` (`boolean`, default ui === "dropzone"): Enables drag-and-drop.
- `preview` (`"none" | "thumbnails"`, default "none"): Thumbnail grid preview (dropzone only).
- `maxFiles` (`number`): Optional max file count.
- `maxFileSize` (`number`): Optional max file size in bytes; oversized files are rejected.
- `clearable` (`boolean`, default true): Shows a clear-all button when possible.
- `showFileList` (`boolean`, default false): Shows the selected-files list below the control.
- `dropLabel / dropHelperText` (`string`, default "Choose a file or drag & drop it here" / —): Dropzone primary/helper text.
- `browseLabel / noFileLabel` (`string`, default "Upload" / "No file chosen"): Browse button label / empty-state text.
- `getFileUploadState` (`(file: File) => { status?; progress?; label? } | undefined`): UI-only upload progress/status for the selected-files list.
- `onClear` (`() => void`): Called when cleared.
- `startIcon / endIcon / prefix / suffix` (`ReactNode`): Adornments on the control.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Switch Field (`/components/form-field-switch`)
- `checked / defaultChecked` (`boolean`): Controlled / uncontrolled checked state.
- `onChange` (`(next: boolean) => void`): Called with the next checked state.
- `showStateText` (`boolean`, default false): Shows inline "On/Off"-style text next to the track.
- `checkedText / uncheckedText` (`ReactNode`, default "On" / "Off"): Text shown for each state (when showStateText).
- `stateTextPlacement` (`"before" | "after" | "both"`, default "after"): Where to render state text relative to the track.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Radio Group Field (`/components/form-field-radio`)
- `options` (`Array<{ label: ReactNode; value: string; disabled?; key? }>`): Items in the group.
- `value / defaultValue` (`string`): Controlled / uncontrolled selection.
- `onChange` (`(next: string) => void`): Called with the next selected value.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `Radio (standalone)` (`component`): A single radio outside a group -- checkbox-shaped (checked/defaultChecked/onChange(checked: boolean)), no labelPlacement.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Checkbox Group Field (`/components/form-field-checkbox`)
- `options` (`Array<{ label: ReactNode; value: string; disabled?; key? }>`): Items in the group.
- `value / defaultValue` (`string[]`): Controlled / uncontrolled selection.
- `onChange` (`(next: string[]) => void`): Called with the next selection.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `Checkbox (standalone)` (`component`): A single checkbox outside a group -- boolean-shaped (checked/defaultChecked/onChange(checked: boolean)), no labelPlacement.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### Date Picker Field (`/components/form-field-datepicker`)
- `value / defaultValue` (`string | { start: string; end: string }`): Controlled / uncontrolled value.
- `onChange` (`(next) => void`): Called when the selection changes.
- `onClear` (`() => void`): Called in addition to onChange when the clear action is used.
- `range` (`boolean`, default false): Enables range mode (value becomes { start, end }).
- `withTime` (`boolean`, default false): Enables time selection alongside the date.
- `showPresets / presets` (`boolean / Array<preset name>`, default false / built-in set): Preset shortcut buttons (Today, This week, …).
- `rangeTrigger` (`"single" | "dual"`, default "single"): Range only: one trigger vs.
- `monthsToShow` (`1 | 2`, default 1 (2 for range)): Calendar months visible at once.
- `displayFormat` (`"pretty" | "iso"`, default "pretty"): Trigger display format.
- `clearable` (`boolean`, default true): Shows a clear action (hidden when required).
- `minDate / maxDate` (`Date | string`): Earliest/latest selectable date.
- `blockedDates` (`Array<Date | string>`, default []): Disabled dates list.
- `startIcon / endIcon / prefix / suffix` (`ReactNode`): Adornments on the trigger.
- `label` (`ReactNode`): Field label.
- `description` (`ReactNode`): Helper text below the control.
- `error` (`ReactNode | boolean`): Error message, or true for an invalid state with no message.
- `size` (`"xs" | "xs-sm" | "sm" | "md" | "lg" | "xl"`, default "md"): Control size.
- `variant` (`"bordered" | "soft" | "filled" | "underlined"`, default "bordered"): Visual variant.
- `color` (`"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | string`, default "default"): Semantic tone.
- `colorDepth` (`number`, default 500): Shade depth for color.
- `radius` (`"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"`, default "md"): Corner radius.
- `labelPlacement` (`"top" | "left" | "right" | "floating"`, default "top"): Label position relative to the control.
- `colSpan` (`number`): Sets `grid-column: span N` on the field wrapper — a real home for a layout hint in a spread config object (instead of leaking to the <input>).
- `wrapperClassName` (`string`): Class on the field wrapper (the element that also carries colSpan), separate from `className` on the control.
- `disabled` (`boolean`, default false): Disables the control.
- `required` (`boolean`, default false): Marks the field required.
- `className` (`string`): Class applied to the root element.
- `style` (`CSSProperties`): Inline styles for the root element.
- `children` (`ReactNode`): FormFieldSet fields and other form content.
- `validationMode` (`"blur" | "change"`, default "blur"): When fields are (re-)validated.
- `showErrorsOn` (`"blur" | "change"`, default "blur"): When validation errors start showing.
- `validateOnMount` (`boolean`, default false): Runs validation immediately on mount.
- `initialValues` (`FormData`, default {}): Initial values for uncontrolled fields.
- `disableAutofill` (`boolean`, default true): Adds autocomplete/autofill-defeating attributes to the form.
- `onSubmit` (`(formData: FormData) => void | Promise<void>`): Called with collected field values on submit (required).
- `onError` (`(errors: FormErrors) => void`): Called when submit is blocked by validation errors.
- `className` (`string`, default ""): Class applied to the form element.

### TextEditor (`/components/text-editor`)
- `value` (`Block[]`, default []): The current block array.
- `placeholder` (`string`, default "Type / to add a block"): Hint shown in an empty paragraph (the focused line, or a lone empty block).
- `allowedBlocks` (`BlockType[]`, default all 17 built-in types): Restricts the slash menu, the toolbar's block-type dropdown and each line's Turn into menu to these types.
- `readOnly` (`boolean`, default false): Disables every block's contentEditable region and hides the drag handle/per-block controls.
- `autoFocus` (`boolean`, default false): Focuses the first block on mount.
- `onChange` (`(blocks: Block[]) => void`): Called with the full block array whenever content changes.
- `onImageUpload` (`(file, { onProgress, signal }) => Promise<string>`): Delegating upload callback for ImageBlock's drop zone — oks-ui doesn't own file storage, it just calls this and displays the returned URL.
- `onFileUpload` (`(file, { onProgress, signal }) => Promise<string>`): Upload callback for the File block's drop zone (non-image attachments); returns the file's URL.
- `onUrlUnfurl` (`(url: string) => Promise<{ title?; description?; image? }>`): Fetches a link's title, description and image for the Bookmark block.
- `label / description / error` (`ReactNode`): Field label, help text and error (error also accepts true for the invalid look).
- `name / validation` (`string / FieldValidation`): Inside a Form, name stores the blocks under that key and validation sets the rules.
- `isDisabled` (`boolean`, default false): Dims the editor and ignores input.
- `labels` (`Partial<TextEditorLabels>`, default English): Every piece of built-in wording (menus, hints, messages, block names) for translation or rewording.
- `maxLength` (`number`): Character limit across the whole document.
- `showCount` (`boolean`, default false): Shows the character and word count under the editor.
- `showPreview` (`boolean`, default false): Adds an Edit / Preview switch.
- `blockClasses` (`boolean`, default false): Adds a settings button to every block with an Additional CSS class(es) field.
- `classOptions` (`{ label: string; className: string }[]`): Ready-made classes offered as toggles in the block settings (needs blockClasses), like WordPress block styles.
- `findReplace` (`boolean`, default true): Ctrl/Cmd+F opens find and replace.
- `onMentionSearch` (`(query, { signal }) => MentionItem[] | Promise<MentionItem[]>`): Turns on @ mentions: called with what was typed, returns people to choose from.
- `emoji` (`boolean`, default false): Typing : and two letters lists matching emoji.
- `maxFileSize` (`number`): Largest upload in bytes; bigger files are refused with a message.
- `onVideoUpload` (`(file, { onProgress, signal }) => Promise<string>`): Uploads a video file; same contract as the image and file callbacks.
- `ref` (`Ref<TextEditorHandle>`): focus(), clear(), insertBlock(), getBlocks(), setBlocks(), getStats(), undo(), redo(), toHtml(), toMarkdown().
- `className` (`string`): Class applied to the root element.

## Patterns

Full product screens assembled from oks-ui — a live preview and the complete
crawlable source, at `https://www.oks-ui.com/patterns/<slug>/`.

- **Analytics dashboard** (`/patterns/analytics-dashboard`): A full fintech app screen — collapsible sidebar, header search, wallet cards, an earnings chart, savings goals, and a transactions table.
- **Sign-in screen** (`/patterns/sign-in`): A split-screen sign-in with a feature panel, Google SSO, and remember-me.
- **Settings panel** (`/patterns/settings-panel`): A real settings screen — top tabs, two-column sections, and a sortable, selectable billing history table.
- **Data table view** (`/patterns/data-table-view`): A full documents list screen — status Tabs, a filter toolbar, and a sortable, selectable Table with real recipient avatars.
- **Sign-up screen** (`/patterns/sign-up`): A dark canvas with a feature pitch, SSO row, and a real registration form.
- **Forgot password** (`/patterns/forgot-password`): A single email field beside an original customer-quote panel.
- **OTP verification** (`/patterns/otp-verify`): Four large circular code boxes with a live resend countdown.
- **Pricing table** (`/patterns/pricing-table`): Four plans with a live billing toggle and a per-feature check/x comparison list.
- **Product grid** (`/patterns/product-grid`): A responsive book grid with ratings, sale pricing, and a save-for-later action.
- **Checkout** (`/patterns/checkout`): A real two-step checkout — order review, discount codes, and a live payment-method switch.
- **Invoice detail** (`/patterns/invoice-detail`): A full-width invoice builder with a live Preview Drawer for the recipient-facing view.
- **Onboarding wizard** (`/patterns/onboarding-wizard`): A 3-column setup flow: a numbered step rail, the active step's form, and contextual tips.
- **Kanban board** (`/patterns/kanban-board`): A full project board — sidebar/header shell, filters, priority cards with subtask checklists, and drag-and-drop with WIP limits.
- **Team members table** (`/patterns/team-members`): A team-settings screen — checkbox-selectable Table, status/group Chips, and a real Pagination footer.
- **Chat thread** (`/patterns/chat`): A full omnichannel inbox — folder/channel rail, a message list, and a real MessageList conversation.
- **Notifications feed** (`/patterns/notifications-feed`): A tabbed notifications card — reactions, comments, attachments, image uploads, and a join request.
- **Calendar & schedule** (`/patterns/calendar-schedule`): A month calendar with event dots, past events, and a paginated upcoming-events list.
- **File manager** (`/patterns/file-manager`): A document-hub dashboard — an action toolbar, suggested folders, and a grid/list file view.
- **Command palette shell** (`/patterns/command-palette-shell`): A full sidebar/header app shell with a real ⌘K command palette wired to the header's search trigger.
- **Empty & error states** (`/patterns/empty-and-error-states`): A real list screen switching between its Loading, Empty, and Error states via Tabs.

## Recipes

Small, focused, copy-paste usage examples rendered on each component page — a
live preview plus the full source, at
`https://www.oks-ui.com/components/<slug>/#recipe-<id>`.

### Button (`/components/button`)
- **Variants** (`#recipe-variants`): Five visual weights, from a filled solid down to an inline link — reach for lighter variants as the action gets more secondary.
- **Semantic colors** (`#recipe-colors`): Colour communicates intent — primary for the main action, success/warning/danger for outcomes. All read from your theme tokens.
- **Sizes** (`#recipe-sizes`): Six size tokens from xs to xl. Pick by density — xs/sm for toolbars and tables, lg/xl for landing-page calls to action.
- **With icons** (`#recipe-icons`): Add a leading or trailing icon with startContent / endContent — spacing and sizing are handled for you. (Bring your own SVG components.)
- **Icon-only** (`#recipe-icon-only`): Set isIconOnly for a square control that holds just an icon — always pass an aria-label so it stays accessible.
- **Loading state** (`#recipe-loading`): isLoading swaps in a spinner and disables the button so it can't be double-submitted. Move the spinner with spinnerPlacement.
- **Full width** (`#recipe-full-width`): fullWidth stretches the button to its container — the norm for forms and mobile CTAs.
- **As a link** (`#recipe-as-link`): Pass as={Link} (or any element/component) and Button renders a real anchor — full button styling, correct link semantics, keyboard and right-click behaviour.

### Card (`/components/card`)
- **Header, body, footer** (`#recipe-anatomy`): Card composes three optional regions — CardHeader, CardBody, CardFooter — so structured content lines up consistently.
- **Hoverable** (`#recipe-hoverable`): isHoverable adds a subtle lift on hover — the cue that a card is interactive or leads somewhere.
- **Clickable card (as a link)** (`#recipe-clickable`): Wrap the whole card in a Link so the entire surface is one focusable target — the pattern for card grids that navigate.
- **KPI card** (`#recipe-kpi`): A compact metric tile — the building block of a dashboard row.
- **Elevation** (`#recipe-shadows`): Dial the shadow from flat to lifted with the shadow scale — match it to how much the card should stand off the page.

### Badge (`/components/badge`)
- **Notification count** (`#recipe-count`): Badge wraps a target and pins a count to its corner — the classic unread indicator on a bell or inbox icon.
- **Capped count** (`#recipe-max`): Pass max and any higher count renders as “max+”, so a busy counter never blows out its width.
- **Status on an avatar** (`#recipe-on-avatar`): A small dot badge on an avatar reads as presence — pair a green dot with a user image.
- **Semantic colors** (`#recipe-colors`): Colour the badge to match meaning — danger for errors, success for done, warning for attention.
- **Placement** (`#recipe-placement`): Pin the badge to any corner with placement — top-end is the default; move it to suit the target.

### Avatar (`/components/avatar`)
- **Image avatar** (`#recipe-image`): Pass src for a photo; name gives it an accessible label and an initials fallback if the image fails to load.
- **Initials fallback** (`#recipe-initials`): With no src, Avatar renders the name's initials — colour it with the color prop for variety across a list.
- **Sizes** (`#recipe-sizes`): Six size tokens (or a raw pixel number) — small for dense lists, large for profile headers.
- **Presence status** (`#recipe-status`): status adds an online/offline/dnd indicator dot — presence without a separate element.
- **Avatar group** (`#recipe-group`): AvatarGroup overlaps avatars and collapses the overflow into a “+N” once past max — the standard “who's on this” cluster.
- **Group with name tooltips** (`#recipe-group-tooltip`): Avatar's own tooltip prop wraps it in a Tooltip -- pass true (or just the prop with no value) to derive the label from name, or a string/object for full control. AvatarGroup clones its size/color/radius/... group defaults onto each Avatar before that wrapping happens, so tooltip composes with it with no extra wiring.

### Chip (`/components/chip`)
- **Variants** (`#recipe-variants`): Four weights — solid, soft, bordered, and a dot variant for status labels.
- **Semantic colors** (`#recipe-colors`): Soft chips make great status pills — colour them by meaning (paid, pending, failed).
- **With an icon** (`#recipe-with-icon`): startContent puts an icon before the label — handy for tags and categories.
- **Closable (removable)** (`#recipe-closable`): Pass onClose and Chip shows a × button — the building block of a filter/token input. Track the list in state and drop the chip on close.
- **With an avatar** (`#recipe-avatar-chip`): The avatar prop tucks a small image at the chip's start — a person or entity token.

### Alert (`/components/alert`)
- **Status colors** (`#recipe-statuses`): Colour maps to intent — success, warning, danger, info — and swaps the leading status icon to match.
- **Variants** (`#recipe-variants`): solid, soft, and bordered — soft is the everyday inline notice; solid draws maximum attention.
- **With actions** (`#recipe-with-actions`): The actions slot holds buttons — a confirm/dismiss inline with the message.
- **Dismissible** (`#recipe-closable`): isClosable adds a × and, when uncontrolled, hides the alert on click — the standard dismissible banner.
- **Custom icon** (`#recipe-custom-icon`): Override the default status icon with your own, or hide it entirely with hideIcon.

### Text Field (`/components/form-field-text`)
- **Basic text field** (`#recipe-basic`): A labelled input with helper text. Wrap fields in a Form so their values are collected and validated together.
- **Leading & trailing icons** (`#recipe-with-icons`): startIcon and endIcon sit inside the control — a search glyph, a status tick — without disturbing the input's own padding.
- **Prefix & suffix affixes** (`#recipe-affixes`): prefix and suffix render attached segments — a currency symbol, a unit, a fixed URL base — that are visually part of the field but never part of its value.
- **Declarative validation** (`#recipe-validation`): validation.rules covers the common cases — required, email, length, pattern — and Form shows the error per-field once it's touched.
- **Floating label** (`#recipe-floating-label`): labelPlacement="floating" starts the label inside the control and animates it up on focus or value — a tighter footprint that still keeps a real, associated label.
- **Visual variants** (`#recipe-variants`): Four surfaces for different densities — bordered by default, soft and filled for grouped forms, underlined for a minimal look.

### Textarea Field (`/components/form-field-textarea`)
- **Basic textarea** (`#recipe-basic`): Multi-line input with a fixed visible height. rows sets the starting line count.
- **Character counter** (`#recipe-length-counter`): showLengthCounter renders a live count against maxLength, so users can see how much room is left before they hit the limit.
- **Required with min length** (`#recipe-validation`): The same rules engine as every field — require the field and enforce a minimum length before submit succeeds.
- **Floating label** (`#recipe-floating-label`): A floating label works on the textarea too — it keeps a persistent, associated label while reclaiming the space a top label would take.

### Select Field (`/components/form-field-select`)
- **Single select** (`#recipe-single`): Pass options as { label, value } pairs. The custom popover is searchable and keyboard-navigable out of the box.
- **Multi-select** (`#recipe-multiple`): multiple turns the value into an array and renders each choice as a removable chip inside the trigger.
- **Options with icons** (`#recipe-with-content`): Each option can carry startContent — a flag, an avatar, a status dot — so the menu reads at a glance, not just as text.
- **Native select** (`#recipe-native`): native swaps the custom popover for the platform's own <select> — lighter, and the right call for dense forms or mobile-first flows.
- **Required select** (`#recipe-validation`): A required select blocks submit until a choice is made, with the error shown in context beneath the trigger.

### Password Field (`/components/form-field-password`)
- **Password with reveal toggle** (`#recipe-basic`): The reveal (eye) toggle is on by default, so users can check what they typed without retyping.
- **Strong-password checklist** (`#recipe-strong-password`): strongPassword shows a live requirements checklist while the field is focused — each rule ticks off as it's met.
- **Hide the reveal toggle** (`#recipe-no-reveal`): Set revealToggle to false for high-security contexts where the value should never be shown back on screen.
- **Custom validation rule** (`#recipe-custom-rule`): Drop to a custom function for anything the built-in rules don't cover — return true to pass, or a string to show as the error.

### Switch Field (`/components/form-field-switch`)
- **Basic switch** (`#recipe-basic`): A labelled toggle with helper text — the standard control for an on/off setting.
- **On by default** (`#recipe-default-on`): Inside a Form the switch is value-driven, so seed its starting state from the Form's initialValues — the same way you'd pre-fill any field.
- **Inline state text** (`#recipe-state-text`): showStateText renders an On/Off label beside the track; override the wording with checkedText and uncheckedText.
- **Required consent** (`#recipe-accept-terms`): A required switch blocks submit until it's turned on — the right pattern for a terms-of-service acknowledgement.

### Radio Group Field (`/components/form-field-radio`)
- **Basic radio group** (`#recipe-basic`): A single-select group from an options array — exactly one value at a time.
- **Default selection** (`#recipe-default-selected`): defaultValue pre-selects an option while keeping the group uncontrolled.
- **Disabled option** (`#recipe-disabled-option`): Mark an individual option disabled to show it exists without letting it be chosen — a plan that's sold out, say.
- **Required group** (`#recipe-required`): A required radio group blocks submit until a choice is made, with the error shown beneath the group.

### Checkbox Group Field (`/components/form-field-checkbox`)
- **Checkbox group** (`#recipe-group`): A multi-select group from an options array — the value is a string[] of the checked values.
- **Default selection** (`#recipe-default-selected`): defaultValue takes an array — pre-check the options that are on by default.
- **Disabled option** (`#recipe-disabled-option`): Disable an individual option to show a capability that isn't available on the current plan.
- **Standalone checkbox** (`#recipe-standalone`): For a single boolean outside a group, import Checkbox directly — it's boolean-shaped with checked/onChange, no options array.

### Range Field (`/components/form-field-range`)
- **Single slider** (`#recipe-single`): A single-thumb slider with the current value shown alongside. min/max default to 0–100.
- **Dual-thumb range** (`#recipe-dual`): selection="range" gives two thumbs and a { min, max } value — for a price band or a date window.
- **Step marks** (`#recipe-marks`): marks draws tick marks along the rail; pair with step so the thumb snaps to each one.
- **Formatted value** (`#recipe-format-value`): formatValue controls how the readout renders — add a unit, a currency symbol, or a percent sign.

### OTP Field (`/components/form-field-otp`)
- **Segmented code** (`#recipe-segmented`): The default UI: one box per digit, with paste-across and arrow-key navigation handled for you.
- **Single input** (`#recipe-single-input`): ui="single" collapses the segments into one text box with a maxLength — lighter, and better on cramped layouts.
- **Alphanumeric code** (`#recipe-alphanumeric`): format="alphanumeric" accepts letters as well as digits — for invite or backup codes rather than numeric OTPs.
- **Shorter code** (`#recipe-short`): length is clamped to 3–8. A 4-digit PIN is a common shorter variant.

### Phone Field (`/components/form-field-phone`)
- **Phone with country code** (`#recipe-basic`): A calling-code selector sits beside the number input; the value is a { code, phone } pair.
- **Default calling code** (`#recipe-default-country`): defaultCountryCode seeds the selector — set it to the market you expect most sign-ups from.
- **No country selector** (`#recipe-hidden-country`): countryCodeMode="hidden" drops the calling-code UI for a plain national number field.
- **Required phone** (`#recipe-required`): The same validation engine applies — require the field before submit succeeds.

### File Field (`/components/form-field-file`)
- **Inline upload** (`#recipe-inline`): The default layout: a browse button with the selected filename beside it — compact enough to sit in a normal form.
- **Drag-and-drop zone** (`#recipe-dropzone`): ui="dropzone" turns the control into a full drop target with browse fallback — for a more prominent upload step.
- **Image thumbnails** (`#recipe-image-previews`): A dropzone with preview="thumbnails" shows a preview grid of the chosen images — pair it with an accept filter.
- **Multiple files with a list** (`#recipe-multiple`): multiple allows several files; showFileList renders the selected files beneath the control with a clear action.

### Date Picker Field (`/components/form-field-datepicker`)
- **Single date** (`#recipe-single`): A calendar popover on a trigger that shows the chosen date. Values are ISO strings (YYYY-MM-DD).
- **Date range** (`#recipe-range`): range mode gives a { start, end } value and a two-month calendar — for a booking or reporting window.
- **Date and time** (`#recipe-with-time`): withTime adds a time picker alongside the calendar; values carry the time (YYYY-MM-DDTHH:mm).
- **Range with quick presets** (`#recipe-presets`): On a range picker, showPresets adds a shortcut panel (Today, Last 7 days, This month, …) so the common windows are one click away.
- **Bounded dates** (`#recipe-bounds`): minDate and maxDate constrain the selectable range — here, no dates in the past.

### Table (`/components/table`)
- **Basic table** (`#recipe-basic`): Pass columns and rows and you get a real, semantic <table> with a styled header — plus a stacked-card fallback on narrow viewports.
- **Sortable columns** (`#recipe-sortable`): Mark a column sortable and its header becomes a sort button with aria-sort. With no onSortChange, Table sorts client-side for you.
- **Row selection** (`#recipe-selectable`): selectionMode="multiple" adds labelled, keyboard-operable checkboxes; keep the selection in your own state via selectedKeys/onSelectionChange.
- **Custom cell rendering** (`#recipe-custom-cells`): A column's render function returns any node for that cell — a status Chip, a formatted number, an avatar — while sorting still works off the raw row value.
- **Loading state** (`#recipe-loading`): isLoading swaps the body for skeleton rows (loadingRowCount controls how many), so the layout never jumps when the real data arrives.

### Modal (`/components/modal`)
- **Confirmation dialog** (`#recipe-basic`): Modal is fully controlled — you own the open state. title is the header, children the body, actions the footer. onClose fires from every dismissal path.
- **Destructive confirm** (`#recipe-destructive`): For a decision the user must make, set role="alertdialog" so screen readers announce it assertively, and lead with a danger action.
- **Sizes** (`#recipe-sizes`): size takes the token scale plus "full" for edge-to-edge — or a raw width. Pick by how much the content needs.
- **Block accidental dismissal** (`#recipe-no-outside-close`): For a multi-step or destructive flow, set closeOnOutsideClick={false} so a stray click on the backdrop can't lose the user's progress.

### Tabs (`/components/tabs`)
- **Basic tabs** (`#recipe-basic`): Render <Tab> children with a title and panel content. Arrow-key navigation and the tablist/tabpanel ARIA pattern are built in — pass an aria-label describing the set.
- **Variants** (`#recipe-variants`): Four visual styles — solid, bordered, light, and underlined — so tabs fit anything from a card header to a full-page section switcher.
- **Accent color** (`#recipe-colors`): color tints the active tab with a semantic tone — pair it with the underlined variant for a clean, branded section switcher.
- **Vertical tabs** (`#recipe-vertical`): isVertical stacks the tab list; pair with placement="start" for a settings-style sidebar layout.
- **Tabs with icons** (`#recipe-with-icons`): A title can be any node — an icon beside a label. When the title isn't plain text, pass titleValue so assistive tech still gets a real name.

### Accordion (`/components/accordion`)
- **One section at a time** (`#recipe-single`): selectionMode="single" closes the previous section when a new one opens — the classic FAQ behavior. Seed the open one with defaultExpandedKeys.
- **Multiple open** (`#recipe-multiple`): The default selectionMode="multiple" lets any number of sections stay open at once — for reference content where users compare sections.
- **Visual variants** (`#recipe-variants`): Three looks: "light" (just dividers), "bordered" (one framed box), and "splitted" (each section its own card).
- **Item subtitles** (`#recipe-subtitle`): An AccordionItem can carry a subtitle beneath its title for a bit of context before the section is even opened.

### Dropdown (`/components/dropdown`)
- **Action menu** (`#recipe-actions`): The compound shape: DropdownTrigger wraps the opener, DropdownMenu holds the items. onAction fires with the activated item's key — usually all you need.
- **Icons and shortcuts** (`#recipe-with-icons`): startContent puts an icon before the label; shortcut renders a keyboard hint aligned to the right.
- **Sections with a divider** (`#recipe-sections`): Group related items under a DropdownSection with a title; showDivider separates a section (like a destructive one) from the rest.
- **Single-select menu** (`#recipe-single-select`): selectionMode="single" makes the menu track a choice — pair with selectedKeys/onSelectionChange to control it. A checkmark marks the active item.
- **Disabled item** (`#recipe-disabled-item`): disabledKeys (or isDisabled on an item) removes an option from keyboard navigation, not just dims it.

### Toast (`/components/toast`)
- **Typed shortcuts** (`#recipe-types`): toast.success / error / warning / info set the type and matching icon. Mount ToastProvider once near your app root; call toast() from anywhere.
- **Title and description** (`#recipe-description`): Pass a description for a second line of context beneath the title.
- **Toast with an action** (`#recipe-action`): An action button turns a notification into something the user can act on — an undo, a reload. Pair it with duration: null so it waits.
- **Promise-aware** (`#recipe-promise`): Hand toast.promise a promise and it walks loading → success/error on its own, so the loading state can't drift from the real request.
- **Persistent until dismissed** (`#recipe-persistent`): persistent removes the auto-dismiss timer — pair with dismissible so the user still has a way to close it. Reserve it for things they must act on.

### Tooltip (`/components/tooltip`)
- **Label an icon button** (`#recipe-basic`): The classic use: a name for an icon-only button. Tooltip opens on hover or keyboard focus, so it's reachable either way — wrap a real focusable element.
- **Placement and arrow** (`#recipe-placement`): placement positions the tooltip (12-way, with auto-flip near edges); showArrow adds a pointer connecting it to the trigger.
- **Semantic colors** (`#recipe-colors`): color tints the tooltip surface — useful to echo the tone of the action it describes.
- **Hover delay** (`#recipe-delay`): A small delay (150–300ms) keeps tooltips on frequently-hovered UI from firing on every incidental mouse pass; closeDelay holds it open briefly after leave.

### Nav (`/components/nav`)
- **Basic navigation** (`#recipe-basic`): Pass items and a renderItem that returns your router's link. isItemActive marks the current route — the active item gets aria-current="page".
- **Icons and badges** (`#recipe-with-icons`): Each item can carry an icon and a badge — a count of unread items, a “New” tag — rendered inline with the label.
- **Multi-level menu** (`#recipe-nested`): children nests to any depth -- a group item (no href, just children) renders a toggle with a caret; clicking it expands/collapses that branch, same as its children can. defaultExpandedKeys opens a branch initially, and the active leaf's ancestors auto-expand.
- **Grouped sections** (`#recipe-sections`): isSection marks a group header; its children nest beneath it. expansionMode="single" makes the groups behave like an accordion.
- **Collapsed icon rail** (`#recipe-collapsed`): isCollapsed shrinks the nav to an icon rail with hover/focus flyouts — each item keeps an accessible name. Give items icons for this mode.
- **Disabled item** (`#recipe-disabled`): isDisabled on an item removes it from keyboard navigation and marks it unavailable — a feature gated behind a plan, say.

### Line Chart (`/components/chart-line`)
- **Single line** (`#recipe-single-series`): The row-based API: pass an array of objects, x for the category field, series for the value field. Line charts read best for a trend over time.
- **Multiple lines** (`#recipe-multi-series`): series accepts an array — pass accessors or { key, name } objects and the legend turns on automatically once there's more than one.
- **Forecast segment** (`#recipe-forecast`): Mark a series isProjection to render it as a dashed forecast continuing from your real data — no second chart to stitch on.
- **Formatted values** (`#recipe-formatted`): dataFormat applies one prefix/suffix/decimals format across labels and tooltips — keep raw numbers in your data and let Chart format them.

### Area Chart (`/components/chart-area`)
- **Single area** (`#recipe-single-series`): Area charts emphasise volume under a trend — same row-based API as line, with the region below the line filled.
- **Multiple areas** (`#recipe-multi-series`): Plot several metrics at once with a series array; the legend appears automatically for comparison.
- **Currency formatting** (`#recipe-formatted`): Use dataFormat for a consistent currency format across the axis, labels, and tooltips.

### Bar Chart (`/components/chart-bar`)
- **Single bar series** (`#recipe-single-series`): Bar charts read best for comparing discrete categories. Pass x for the category and series for the value.
- **Grouped bars** (`#recipe-grouped`): A series array plots grouped bars per category — useful for comparing two measures side by side.
- **Currency formatting** (`#recipe-formatted`): dataFormat keeps currency formatting consistent across labels and tooltips without pre-formatting your data.

### Column Chart (`/components/chart-column`)
- **Single column series** (`#recipe-single-series`): Columns are vertical bars — a natural fit for a value per time period, like revenue by quarter.
- **Grouped columns** (`#recipe-grouped`): A series array renders grouped columns per category for a side-by-side comparison.
- **Projected columns** (`#recipe-forecast`): isProjection splits column charts too — projected columns get their own treatment on the same axis scale as the actuals.

### Pie Chart (`/components/chart-pie`)
- **Basic pie** (`#recipe-basic`): Pie charts show part-to-whole for a small number of categories — x is the slice label, series the value.
- **Tooltip with total** (`#recipe-tooltip-total`): tooltip options can show a running total across the slices — handy for a part-to-whole where the whole matters too.
- **Percentage labels** (`#recipe-formatted`): dataFormat with a suffix renders percentages consistently in the labels and tooltip.

### Donut Chart (`/components/chart-donut`)
- **Basic donut** (`#recipe-basic`): A donut is a pie with a hollow center — same part-to-whole data, a little more room for a legend or a total in the middle.
- **Total in the center** (`#recipe-center-total`): The donut hole is yours — pie.renderCenter draws into it. A running total is the classic use.
- **Percentage labels** (`#recipe-formatted`): Format the slice values as percentages with dataFormat.

### Heatmap Chart (`/components/chart-heatmap`)
- **Matrix heatmap** (`#recipe-matrix`): A heatmap wants a matrix: one row per x-category, a numeric column per series. Here, activity by time-of-day (rows) across weekdays (series).
- **Formatted cells** (`#recipe-formatted`): dataFormat carries into the cell tooltips — add a unit so each cell's value reads clearly.

### Chart States (`/components/chart-states`)
- **Loading state** (`#recipe-loading`): isLoading swaps in a dedicated loading state in place of the plot — pass it straight from your data hook so the chart keeps its size while data loads.
- **Error state** (`#recipe-error`): error renders an error state instead of the plot — feed it your fetch error so a failed load reads clearly.
- **Empty state** (`#recipe-empty`): empty covers the no-data case — a distinct message rather than a blank, confusing chart frame.

### Divider (`/components/divider`)
- **Horizontal rule** (`#recipe-basic`): The default: a full-width horizontal line to separate stacked content.
- **Labelled divider** (`#recipe-labelled`): Pass children for an inline label — the classic “OR” between two options. labelPlacement moves the text.
- **Vertical divider** (`#recipe-vertical`): orientation="vertical" separates inline items — actions in a toolbar, stats in a row.
- **Line styles** (`#recipe-styles`): lineStyle switches between solid, dashed, and dotted; color and thickness tune the rest.

### Loader (`/components/loader`)
- **Spinner variants** (`#recipe-variants`): Seven built-in animations — ring styles, a pulse, and dot sequences. Pick one that matches the surrounding UI's weight.
- **Sizes and color** (`#recipe-sizes`): size takes the token scale or a raw pixel number; color tints it to a semantic tone.
- **Inside a button** (`#recipe-in-button`): Drop a small white loader into a button for an inline pending state (Button's own isLoading does this for you too).

### Skeleton (`/components/skeleton`)
- **Shapes** (`#recipe-shapes`): Three primitive shapes — text, rect, and circle — sized with width/height to match whatever they stand in for.
- **Multi-line text** (`#recipe-text-lines`): variant="text" with lines renders a stack of text placeholders — the last line comes up short, like a real paragraph.
- **Wrap until loaded** (`#recipe-wrap`): Wrap real content and flip isLoaded when data arrives — Skeleton shows the placeholder, then reveals the children in place with no layout shift.
- **Composed card skeleton** (`#recipe-card`): Compose the primitives to mirror a real card's layout so the loading state has the same shape as the content it replaces.

### Progress (`/components/progress`)
- **Linear progress** (`#recipe-linear`): A determinate bar from value against minValue/maxValue (default 0–100). showValueLabel prints the percentage.
- **Circular progress** (`#recipe-circular`): CircularProgress is the ring variant — same value API, for a compact inline indicator.
- **Indeterminate** (`#recipe-indeterminate`): Omit value for an indeterminate animation when you can't measure progress — a request in flight, say.
- **Semantic colors** (`#recipe-colors`): color communicates the state of what's progressing — success as it completes, danger when it's over a limit.

### PageTitle (`/components/page-title`)
- **Title and subtitle** (`#recipe-basic`): A page or section header — title plus an optional subtitle beneath it, at a consistent size across the app.
- **With a leading icon** (`#recipe-with-icon`): icon renders before the title (iconPosition moves it to the end) — useful for a section that maps to a nav item.
- **Accent color** (`#recipe-colored`): color tints the title — reach for it sparingly, to flag a section's status.

### EmptyState (`/components/empty-state`)
- **Empty list** (`#recipe-basic`): A centered placeholder for a list with nothing in it yet — icon, title, description, and a primary action.
- **No search results** (`#recipe-no-results`): The other common case: a search or filter that matched nothing, with a way to clear it.
- **Compact size** (`#recipe-sizes`): size="sm" fits an empty state inside a card or a small panel without dominating it.

### Stat (`/components/stat`)
- **KPI row** (`#recipe-group`): StatGroup lays out a responsive row of KPI blocks with dividers between them — a label, a big value, and a trend delta.
- **Trend direction** (`#recipe-trend`): A numeric delta shows an up/down pill by sign; the direction is conveyed with an arrow and text, not colour alone.
- **With an icon** (`#recipe-with-icon`): icon adds a leading glyph to reinforce what the metric measures; help adds a small hint.

### Timeline (`/components/timeline`)
- **Activity feed** (`#recipe-basic`): A vertical feed of events on a connector rail. Each TimelineItem has a title, an optional time, and body content.
- **Colored markers** (`#recipe-colored-markers`): color tints an item's marker to signal status — success for a completed step, danger for a failure.
- **Icon markers** (`#recipe-with-icons`): Swap the dot for an icon per item to make each event type recognisable at a glance.

### ButtonGroup (`/components/button-group`)
- **Joined buttons** (`#recipe-basic`): ButtonGroup joins a set of related actions into one segmented control with shared borders and radius.
- **Shared appearance** (`#recipe-shared-props`): Props on the group cascade to every button — set variant, color, and size once instead of per button.
- **Icon buttons** (`#recipe-with-icons`): A group of icon-only buttons makes a compact toolbar — each still needs an aria-label.
- **Full width** (`#recipe-full-width`): fullWidth stretches the group to fill its container, splitting the space evenly — good for a mobile segmented switch.

### Breadcrumbs (`/components/breadcrumbs`)
- **Basic trail** (`#recipe-basic`): A navigation trail — each BreadcrumbItem with an href is a link; the last item is the current page (no link, aria-current). Separators are drawn in CSS.
- **Collapse a long path** (`#recipe-collapsed`): maxItems collapses the middle of a deep path to an ellipsis (that expands on click), keeping the first and last crumbs visible.
- **Icon in a crumb** (`#recipe-with-icon`): A crumb's children can include an icon — a home glyph on the root is the common case.
- **Router links** (`#recipe-router-links`): Pass `as` to render each crumb through your router's link component instead of a plain anchor.

### Pagination (`/components/pagination`)
- **Page control** (`#recipe-basic`): A windowed page-number control — pass the current page, the total pageCount, and an onChange to move between pages.
- **With a results summary** (`#recipe-with-summary`): PaginationSummary prints a “Showing X–Y of Z” line — pair it with Pagination in a list or table footer.
- **Table footer** (`#recipe-table-footer`): The typical composition: a summary on the left, page control on the right, beneath a table.

### SegmentedControl (`/components/segmented-control`)
- **View switcher** (`#recipe-basic`): A compact switch between a few mutually exclusive options, with an animated thumb. Controlled via value/onChange.
- **Sizes** (`#recipe-sizes`): size tunes the control's density — sm for toolbars, lg for a prominent switch.
- **Full width** (`#recipe-full-width`): fullWidth stretches the control to fill its container with equal segments — good for a mobile tab-style switch.

### Backdrop (`/components/backdrop`)
- **Overlay primitive** (`#recipe-basic`): Backdrop is the bare dimmed overlay behind Modal/Drawer — reach for it directly for a lightbox or a custom centered overlay. You own isOpen/onClose.
- **Blur and opacity** (`#recipe-blur`): blur frosts the content behind the overlay; backgroundOpacity controls how dark the scrim is.
- **Entrance animation** (`#recipe-animation`): animationType controls how the overlay and its content enter and exit.

### Drawer (`/components/drawer`)
- **Slide-over panel** (`#recipe-basic`): Same controlled shape as Modal — you own isOpen, and onClose fires from every dismissal path. Slides in from the right by default.
- **Any edge** (`#recipe-positions`): position picks the edge it slides from — left, right, top, or bottom. width sizes left/right drawers; height sizes top/bottom ones.
- **Header, body, footer** (`#recipe-with-actions`): The same three slots as Modal — title, children, and an actions footer for the confirm/cancel buttons.

### Message (`/components/message`)
- **Chat thread** (`#recipe-thread`): MessageList is a live log; each Message is a bubble aligned start (received) or end (sent), with an author, avatar, and timestamp.
- **Delivery status** (`#recipe-status`): status shows a sent/delivered/read/failed indicator on your own messages — exposed as text to assistive tech, not just an icon.
- **Grouped continuation** (`#recipe-continuation`): isContinuation tucks a follow-up bubble from the same author tighter under the previous one, dropping the repeated avatar while keeping its own timestamp.

### SplitLayout (`/components/split-layout`)
- **Master–detail** (`#recipe-master-detail`): Two panes with a keyboard-resizable divider — a sized list on the left, a flexible detail pane on the right. Set isResizable on the pane you want draggable.
- **Three-pane** (`#recipe-three-pane`): A classic mail layout: a collapsible folder rail, a resizable message list, and a flexible reading pane.
- **Vertical split** (`#recipe-vertical`): direction="vertical" stacks panes with a horizontal divider — an editor above, a preview or console below.

### CommandPalette (`/components/command-palette`)
- **⌘K command menu** (`#recipe-hotkey`): useCommandPalette wires up the ⌘/Ctrl+K hotkey and open state; spread getPaletteProps() onto CommandPalette. Items are grouped and fuzzy-filtered as you type.
- **Grouped items with shortcuts** (`#recipe-items`): Each item carries a label, a group, optional icon, shortcut, description, and keywords for fuzzy matching beyond the visible label.
- **Controlled open state** (`#recipe-controlled`): Skip the hook and drive it directly with isOpen/onClose when something other than the hotkey opens it — a toolbar button, a first-run tour.

### Board (`/components/board`)
- **Kanban board** (`#recipe-kanban`): Board takes columns plus a flat items array — getItemColumn places each item, renderCard draws it, and onItemMove reports drag/keyboard moves as { itemId, to }.
- **Column WIP limits** (`#recipe-column-limits`): A column's limit caps how many cards it accepts. A move from another column that would exceed it is refused, and keyboard users hear that the column can't take the card. Reordering inside a full column still works.

### SteppedForm (`/components/stepped-form`)
- **Multi-step wizard** (`#recipe-wizard`): Each step declares the fields it validates before advancing; every field registers with the form up front, so the final submit validates the whole schema, not just the last step.
- **Header styles** (`#recipe-header-variant`): headerVariant picks the step indicator — dots (default), progress (a filled bar), tabs (clickable labels), or none to render your own.

### Calendar (`/components/calendar`)
- **Single date** (`#recipe-single`): A standalone month grid with full keyboard navigation. value/onChange use ISO date strings (YYYY-MM-DD).
- **Date range** (`#recipe-range`): selectionMode="range" selects a start–end window; the value becomes a { start, end } pair of ISO strings.
- **Constrain selectable days** (`#recipe-bounds`): minValue/maxValue bound the range; isDateUnavailable disables specific days (weekends here) — both are skipped by keyboard navigation.

### TextEditor (`/components/text-editor`)
- **Block editor with Edit / Preview** (`#recipe-basic`): A controlled block editor: value is an array of Block objects and onChange gives you the updated tree. Type / on an empty line to add a heading, list, table and more; select text to format it. showPreview adds an Edit / Preview switch, and Preview shows the page as a reader sees it, at desktop, tablet or phone width.
- **Custom CSS classes on a block** (`#recipe-classes`): blockClasses puts a settings button beside every block with an Additional CSS class(es) field, like the WordPress block editor. classOptions adds ready-made classes as toggles. The classes are kept in block.props.className, shown on the block while you edit, and written to the HTML export, so your own stylesheet gives them a look.
- **Mentions and emoji** (`#recipe-mentions`): Pass onMentionSearch and typing @ opens a list under the caret, filled by your function (it may return a promise and gets an abort signal). emoji turns on the : picker. A mention is stored with its id, so you keep control of the names.
- **Character limit and count** (`#recipe-limit`): maxLength caps the characters of the whole document: typing, dropping and pasting stop at the limit. showCount shows the characters and words under the editor.
- **A block of your own** (`#recipe-custom-block`): registerBlock adds a block type of your own (a poll, a product card). It joins the slash menu, undo, drag and copy and paste, and is stored as { type, props } in the document. Type / and choose Poll.
- **Limit block types** (`#recipe-allowed-blocks`): allowedBlocks trims the slash menu to a subset — a comment field that only needs paragraphs and lists, say, instead of every block type.
- **Read-only render** (`#recipe-read-only`): readOnly renders the same block content as static, non-editable output — for displaying saved documents with the editor's own styling.

## Templates

Full applications built entirely on oks-ui, hosted and running live, with the
source published for most. See https://www.oks-ui.com/templates/ — open one to
click through the real product, and read the code where it is public.

- **Astrobit** (https://oks-projects.github.io/astrobit/): Dark-first analytics workspace
  A workspace admin console — analytics home, revenue breakdowns, a command palette, and a widget-driven dashboard. Leans on Chart, CommandPalette, and the dark token set.
  166 screens · 33 oks-ui components · Vite · React 19 · dark theme · source: https://github.com/OKS-PROJECTS/astrobit
  - Dark-first: Built on the dark token set, with the light theme as the switch rather than the default.
  - Command palette: Cmd-K navigation across the whole app, from oks-ui CommandPalette.

- **Bilkoss** (https://oks-projects.github.io/bilkoss/): Light e-commerce admin
  A storefront back-office — orders, revenue, and store performance across a light, airy layout. Shows Stat, Chart, Table, and Avatar working together at dashboard density.
  153 screens · 35 oks-ui components · Vite · React 19 · light theme · source: https://github.com/OKS-PROJECTS/bilkoss
  - Store back-office: Orders, revenue and store performance at dashboard density, in a light, airy layout.
  - Data tables: Sorting, selection and pagination composed from Table, not a second table library.

- **Cearix** (https://oks-projects.github.io/cearix/dashboards/sales): Multi-dashboard admin console
  An admin template carrying sales, crypto, and analytics dashboards plus list, detail, and settings screens and a component gallery. Application pages are config-driven archetypes fed from mock data — no second UI, charting, or form library.
  146 screens · 36 oks-ui components · Vite · React 19 · light theme · source: https://github.com/OKS-PROJECTS/cearix
  - Three dashboards: Sales, crypto and analytics, each a different shape of the same primitives.
  - Config-driven pages: List, detail and settings screens are config objects fed from mock data, not bespoke components.

- **Dyloc** (https://oks-projects.github.io/dyloc/dashboards/default): Config-driven admin template
  A full admin surface — shell, dashboards, tables, charts, forms, and settings — composed entirely from oks-ui primitives. List, form, settings, and detail screens are config objects rather than bespoke components, and every colour flips from one token file.
  92 screens · 34 oks-ui components · Vite · React 19 · light theme · source: https://github.com/OKS-PROJECTS/dyloc
  - One token file: Every colour in the app flips from a single token file — the theming argument, demonstrated.
  - Archetype screens: List, form, settings and detail render through one archetype from config.

- **Elosh** (https://oks-projects.github.io/elosh/dashboard/employee): HR & workforce admin dashboard
  A workforce console — employee directory, org dashboards, reports, and settings, plus a component gallery. List, form, settings, and report screens render through one archetype from config objects, and the primary ramp re-skins the whole app in light or dark.
  116 screens · 32 oks-ui components · Vite · React 19 · light theme · source: https://github.com/OKS-PROJECTS/elosh
  - Workforce console: Employee directory, org dashboards, reports and settings, plus a component gallery.
  - Light and dark: The primary ramp re-skins the whole app in either theme.

- **Verox** (https://oks-projects.github.io/verox/): Admin template with built-in apps
  An admin template that goes past dashboards into the apps a workspace actually runs on — email, chat, a team board, a calendar, invoices and an issue tracker — alongside stat cards, a multi-series performance chart and a component gallery. Every screen is composed from oks-ui primitives.
  90 screens · 37 oks-ui components · Vite · React 19 · TypeScript · light theme · source: https://github.com/OKS-PROJECTS/verox
  - Apps, not just charts: Email, chat, a team board, a calendar, invoices and an issue tracker alongside the dashboards.
  - Layout options: Boxed, compact and horizontal layouts, plus dark, gray and hover variants of the sidebar and topbar.

## Blog

Tutorials and engineering notes at `https://www.oks-ui.com/blog/`.
RSS: https://www.oks-ui.com/blog/feed.xml

- **Drawing charts in React with no charting library** (`/blog/react-charts-without-a-charting-library`, 2026-10-09): How a chart is drawn as plain SVG in React: scales, ticks and paths in 60 lines, and what a real chart gets wrong, reproduced on three oks-ui versions.
- **A zero-dependency React rich text editor: what broke** (`/blog/react-rich-text-editor-no-dependencies`, 2026-10-09): How the oks-ui TextEditor was built with no dependencies, what broke along the way, and how each problem was measured on 1.1.2, 1.2.2 and 1.4.1.
- **An accessibility audit of oks-ui: what is still open** (`/blog/oks-ui-accessibility-audit`, 2026-10-09): What axe-core, a keyboard-only pass and seven oks-ui versions found: what 1.2 and 1.3 fixed, and the problems that are still open.
- **React Modal guide: sizes, closing and backdrop, tested** (`/blog/react-modal-component-guide`, 2026-10-07): A guide to the React Modal: sizes, confirmations, forms and closing, tested in three browsers, with two unit traps and the dismissible gotcha found.
- **Build a file upload field in React, tested in three browsers** (`/blog/react-file-upload-size-type-limits`, 2026-10-06): A React file upload field with drag and drop, size and type limits, tested in three browsers, with the ignored limit props and the missing import found.
- **Build a SaaS settings page in React, tested in three browsers** (`/blog/build-saas-settings-page-react`, 2026-10-03): A SaaS settings page built with oks-ui and tested in three browsers, with four fixes: the toast, the delete dialog, the save bar and dark-mode text colour.
- **oks-ui 1.2: what changed and why, measured against 1.1.2** (`/blog/oks-ui-1-2-release`, 2026-10-01): What changed in oks-ui 1.2 and why: bundle size, WCAG contrast, focus traps and the TextEditor, with 1.1.2 and 1.2.0 measured side by side.
- **Per-component imports in oks-ui: what they really save, measured** (`/blog/reduce-react-bundle-size-per-component-imports`, 2026-09-29): We measured oks-ui two ways. JavaScript is identical whether you import from the main entry or per component; CSS is where per-component imports save.
- **React server-side sorting table, tested in three browsers** (`/blog/react-table-server-side-sorting-paging`, 2026-09-27): A React table with server-side sorting and paging against a real API, tested in three browsers, with a missing loading state fixed and the API advice checked.
- **oks-ui 1.2.2: what changed and why, checked against 1.2.1** (`/blog/oks-ui-1-2-2-release`, 2026-09-25): What changed in oks-ui 1.2.2 and why: the Badge number type error, the missing MIT license file and the dead bug link, checked against 1.2.1.
- **React Button guide: variants, sizes and loading, tested** (`/blog/react-button-component-guide`, 2026-09-25): A guide to the React Button's variants, sizes, loading and links, tested in three browsers: contrast measured across 210 combinations, four claims corrected.
- **Build a multi-step form in React, tested in three browsers** (`/blog/react-multi-step-form-with-progress`, 2026-09-23): A React multi-step form with per-step validation, tested in three browsers, with two wrong claims fixed and three gaps found in oks-ui's SteppedForm.
- **Getting started with oks-ui in React, tested from scratch** (`/blog/getting-started-with-oks-ui`, 2026-09-20): Getting started with oks-ui, run on fresh Vite and Next.js apps in three browsers, with the broken code, the CSS import trap and dark mode fixed.
- **Build a date range picker in React, tested in three browsers** (`/blog/react-date-range-picker-with-presets`, 2026-09-19): A React date range picker with presets, limits and time, tested in three browsers and time zones, with what each preset gives and the keyboard gaps found.
- **Build an admin dashboard in React, tested in three browsers** (`/blog/build-admin-dashboard-in-react`, 2026-09-17): An oks-ui admin dashboard tested in three browsers, with a missing import fixed and a dark-mode bug and two contrast gaps found in the library.
- **Accessible React Modal: Focus Trap and Escape Key** (`/blog/accessible-react-modal-focus-trap`, 2026-09-15): The five things an accessible React modal must do, tested in Chromium, Firefox and WebKit with oks-ui's Modal, plus a 30-second keyboard test.
- **Build a login form in React, tested in three browsers** (`/blog/react-login-form-with-validation`, 2026-09-12): A React login form with validation, autofill and a double-submit guard, tested in three browsers, with one wrong claim fixed and two library gaps found.
- **Drag-and-drop in the oks-ui Board, tested in three browsers** (`/blog/dependency-free-drag-and-drop-inside-board`, 2026-09-09): Board's mouse, touch and keyboard drag-and-drop tested in Chromium, Firefox and WebKit, with the gaps I found and a script to check your own board.
- **Dark mode with no flash, tested in three browsers** (`/blog/dark-mode-with-no-flash`, 2026-09-05): A synchronous script in the head stops the dark-mode flash. Tested in Chromium, Firefox and WebKit, including a bug found on this site and two corrected claims.
- **Build a sortable React data table, tested in three browsers** (`/blog/build-a-sortable-selectable-data-table`, 2026-09-03): A React data table with search, sort, selection and paging, tested in three browsers, with the sort and search bugs in the first version fixed.
- **Theme oks-ui to your brand, tested in light and dark** (`/blog/theme-oks-ui-to-your-brand-in-10-minutes`, 2026-08-28): How to theme oks-ui to your brand, tested in light and dark, with the shades components really read and the first version's broken hover and dark mode.

## FAQ

**What is oks-ui?**
oks-ui is a React component library written in strict TypeScript, with a design system driven entirely by CSS custom properties. It ships 45 components — buttons, modals, drawers, forms, tables, charts, toasts, a command palette, a Kanban board, a block editor and more — has zero runtime dependencies beyond React, needs no theme provider or configuration, and has keyboard support, visible focus, ARIA roles and reduced-motion handling built into its interactive components. It is open source under the MIT License.

**Is oks-ui free? What license is it under?**
Yes, oks-ui is free. The package is open source under the MIT License, which permits use in personal and commercial projects at no cost. The documentation website's terms apply only to the site, not to your use of the package.

**How do I install oks-ui?**
Run `npm install oks-ui` (or `pnpm add oks-ui` / `yarn add oks-ui`). Import the stylesheet once in your app entry or root layout with `import "oks-ui/styles.css"`. Then import components as named exports, for example `import { Button } from "oks-ui"`. There is no provider to add and no configuration step.

**Does oks-ui work with Next.js and React Server Components?**
Yes. oks-ui works with the Next.js App Router. Since oks-ui 1.3.1 the per-component entries (oks-ui/button, oks-ui/modal, and so on) are marked as client components, so you can import them straight into a Server Component and Next.js still prerenders their initial HTML. The exceptions are oks-ui/text-editor and oks-ui/pagination, which also export plain functions a server can call, and the main oks-ui entry: import their components only inside a file that starts with "use client". On oks-ui 1.2.x no entry is marked, so add "use client" to every file that renders a component.

**Does oks-ui need a provider or configuration?**
No. There is no theme provider, no configuration object, and no required setup beyond importing the stylesheet once. The one exception is Toast, which uses its own provider to manage the notification queue.

**How do I theme oks-ui or change its colors?**
Every color, space, radius and shadow is an --oks-* CSS custom property. Override any token from your own CSS with no build step or config file, for example `:root { --oks-color-primary-500: #7c3aed; }`. Semantic roles such as primary, secondary, success, warning and danger are aliases you can point at any built-in palette or your own scale. Dark mode is driven by a data-theme="dark" attribute on the html element.

**Does oks-ui have runtime dependencies?**
No. The only peer dependencies are react and react-dom. Nothing else is added to your bundle, which keeps install size small and avoids transitive version conflicts.

**Is oks-ui accessible?**
Accessibility is a core design goal. Interactive components ship with keyboard navigation, :focus-visible focus rings, appropriate ARIA roles and attributes, and prefers-reduced-motion support. Overlay components such as Modal and Drawer include focus trapping and restore focus on close. Non-interactive components such as Badge, Divider and Stat have no keyboard behavior to add.

**Do I have to use TypeScript to use oks-ui?**
No. oks-ui is written in strict TypeScript and ships complete type definitions, so TypeScript users get full type checking and editor hints, but the package works the same in plain JavaScript projects.

**Which React versions does oks-ui support?**
oks-ui supports React 18 and newer, including React 19.

**How big is oks-ui and does it tree-shake?**
oks-ui has no runtime dependencies, so the only code that reaches your bundle is the components you import. Components are named exports and the package is side-effect-free apart from the CSS you import explicitly, so bundlers can drop the components you do not use. Per-component subpaths (for example `oks-ui/button`) let you import just one component and its CSS without pulling in the rest of the library at all.

**Is oks-ui production-ready and how is it versioned?**
oks-ui is published to npm and follows semantic versioning, so breaking changes come only in major releases. The current version is always shown on the npm page at https://www.npmjs.com/package/oks-ui.

**Where are the docs and how do I get help?**
Documentation lives at https://www.oks-ui.com/docs, with an interactive props playground for every component at https://www.oks-ui.com/components. Full application examples are at https://www.oks-ui.com/templates and https://www.oks-ui.com/patterns.