# Introduction
URL: /docs/introduction



## Key Features [#key-features]

* **Composable by design** - Build complex interfaces by combining simple, focused components
* **Built on top of shadcn/ui** - Uses the same design principles and styling approach as shadcn/ui
* **Copy-paste ready** - Same installation experience as shadcn/ui components
* **Fully customizable** - Built with Tailwind CSS and designed to match your design system
* **Advanced functionality** - Complex components like data tables, media players, and drag-and-drop interfaces

## Why Dice UI? [#why-dice-ui]

Dice UI is a collection of fully composable components that extend shadcn/ui. These components are accessible and customizable to fit your needs. Dice UI is copy-paste ready, no complex setup or configuration required.
Every component follows WCAG guidelines, includes proper ARIA attributes, and supports keyboard navigation out of the box.

## Credits [#credits]

* [Base UI](https://base-ui.com) - Default component primitives.
* [Radix UI](https://radix-ui.com) - Alternative component primitives.
* [shadcn/ui](https://ui.shadcn.com) - Components design and registry distribution.
* [Fumadocs](https://fumadocs.vercel.app) - Documentation.


# December 2024 - Initial Release
URL: /docs/changelog/2024-12-initial-release



Dice UI launched with a set of accessible components built on Radix UI primitives. Tags Input, Combobox, Checkbox Group, and Mention also ship as `@diceui/*` npm packages.

* **Tags Input**
* **Combobox**
* **Sortable**
* **Kbd**
* **Checkbox Group**
* **Mention**

### Tags Input [#tags-input]

Display a list of tags in an input field with the ability to add, edit, and remove them.

<ComponentTabs name="tags-input-demo" base="radix" />

[Read the docs](/docs/components/radix/tags-input)

### Combobox [#combobox]

An input with a popover that helps users filter through a list of options.

<ComponentTabs name="combobox-demo" base="radix" />

[Read the docs](/docs/components/radix/combobox)

### Sortable [#sortable]

A drag and drop sortable component for reordering items.

<ComponentTabs name="sortable-demo" />

[Read the docs](/docs/components/sortable)

### Kbd [#kbd]

A keyboard key primitive for displaying keyboard shortcuts and key combinations.

[Read the docs](/docs/components/radix/kbd)

### Checkbox Group [#checkbox-group]

A group of checkboxes that allows multiple selections with support for validation and accessibility.

<ComponentTabs name="checkbox-group-demo" base="radix" />

[Read the docs](/docs/components/radix/checkbox-group)

### Mention [#mention]

A component that allows to mention items in a list by a trigger character.

<ComponentTabs name="mention-demo" base="radix" />

[Read the docs](/docs/components/radix/mention)


# February 2025 - New Components
URL: /docs/changelog/2025-02-new-components



We've added drag and drop boards, layout components, and the first utilities.

* **Kanban**
* **Masonry**
* **Editable**
* **Scroller**
* **Relative Time Card**
* **Composition**
* **Portal**

### Kanban [#kanban]

A drag and drop kanban board component for organizing items into columns.

<ComponentTabs name="kanban-demo" />

[Read the docs](/docs/components/kanban)

### Masonry [#masonry]

A responsive masonry layout component for displaying items in a grid.

<ComponentTabs name="masonry-demo" />

[Read the docs](/docs/components/masonry)

### Editable [#editable]

An accessible inline editable component for editing text content in place.

<ComponentTabs name="editable-demo" />

[Read the docs](/docs/components/editable)

### Scroller [#scroller]

A scrollable container with customizable scroll shadows and navigation buttons.

<ComponentTabs name="scroller-demo" />

[Read the docs](/docs/components/scroller)

### Relative Time Card [#relative-time-card]

A hover card that displays relative time relative to local time with timezone information.

<ComponentTabs name="relative-time-card-demo" />

[Read the docs](/docs/components/relative-time-card)

### Composition [#composition]

A collection of utility functions for composing event handlers and refs in React components.

[Read the docs](/docs/utilities/composition)

### Portal [#portal]

Renders React elements into a different part of the DOM tree.

[Read the docs](/docs/utilities/portal)


# March 2025 - Data Table and Listbox
URL: /docs/changelog/2025-03-data-table



We've added a Data Table and a Listbox.

* **Data Table**
* **Listbox**

### Data Table [#data-table]

A powerful and flexible data table component for displaying, filtering, sorting, and paginating tabular data.

<ComponentTabs name="data-table-demo" />

[Read the docs](/docs/components/data-table)

### Listbox [#listbox]

A component for creating keyboard-navigable selection lists and grids.

<ComponentTabs name="listbox-demo" base="radix" />

[Read the docs](/docs/components/radix/listbox)


# April 2025 - File Upload and Media Player
URL: /docs/changelog/2025-04-file-upload-media-player



We've added components for uploading files and playing media.

* **File Upload**
* **Media Player**
* **Presence**

### File Upload [#file-upload]

A file upload component with drag and drop, previewing, and progress tracking.

<ComponentTabs name="file-upload-demo" />

[Read the docs](/docs/components/file-upload)

### Media Player [#media-player]

A fully featured media player component supporting video and audio playback with custom controls.

<ComponentTabs name="media-player-demo" />

[Read the docs](/docs/components/media-player)

### Presence [#presence]

Manages element mounting and unmounting with animation support.

[Read the docs](/docs/utilities/presence)


# August 2025 - Color Picker
URL: /docs/changelog/2025-08-color-picker



We've added components for picking and displaying colors, and grouped inputs.

* **Color Picker**
* **Color Swatch**
* **Segmented Input**

### Color Picker [#color-picker]

A color picker component that allows users to select colors using various input methods.

<ComponentTabs name="color-picker-demo" />

[Read the docs](/docs/components/color-picker)

### Color Swatch [#color-swatch]

A color swatch component for displaying color values with support for transparency and various sizes.

<ComponentTabs name="color-swatch-demo" />

[Read the docs](/docs/components/color-swatch)

### Segmented Input [#segmented-input]

A group of connected input fields that appear as a single segmented visual unit. It shipped as Input Group and was renamed to Segmented Input in November 2025.

<ComponentTabs name="segmented-input-demo" />

[Read the docs](/docs/components/segmented-input)


# September 2025 - New Components
URL: /docs/changelog/2025-09-new-components



We've added six new components.

* **Stepper**
* **Avatar Group**
* **Mask Input**
* **Cropper**
* **Angle Slider**
* **Circular Progress**

### Stepper [#stepper]

A component that guides users through a multi-step process with clear visual progress indicators.

<ComponentTabs name="stepper-demo" />

[Read the docs](/docs/components/stepper)

### Avatar Group [#avatar-group]

A component that arranges avatars with overlapping visual effects for displaying multiple users or items. It shipped as Avatar and was renamed to Avatar Group in November 2025.

<ComponentTabs name="avatar-group-demo" />

[Read the docs](/docs/components/avatar-group)

### Mask Input [#mask-input]

An input component that formats user input with predefined patterns like phone numbers, dates, and credit cards.

<ComponentTabs name="mask-input-demo" />

[Read the docs](/docs/components/mask-input)

### Cropper [#cropper]

A powerful image and video cropper with zoom, rotation, and customizable crop areas.

<ComponentTabs name="cropper-demo" />

[Read the docs](/docs/components/cropper)

### Angle Slider [#angle-slider]

An interactive circular slider for selecting angles with support for single values and ranges.

<ComponentTabs name="angle-slider-demo" />

[Read the docs](/docs/components/angle-slider)

### Circular Progress [#circular-progress]

A circular progress indicator that displays completion progress in a ring format with support for indeterminate states.

<ComponentTabs name="circular-progress-demo" />

[Read the docs](/docs/components/circular-progress)


# October 2025 - Data Grid
URL: /docs/changelog/2025-10-data-grid



We've added a spreadsheet-style Data Grid and a handful of smaller components.

* **Data Grid**
* **Marquee**
* **Rating**
* **QR Code**
* **Hitbox**

### Data Grid [#data-grid]

A high-performance editable data grid component with virtualization, keyboard navigation, and comprehensive cell editing capabilities.

<ComponentTabs name="data-grid-demo" />

[Read the docs](/docs/components/data-grid)

### Marquee [#marquee]

An animated scrolling component that continuously moves content horizontally or vertically.

<ComponentTabs name="marquee-demo" />

[Read the docs](/docs/components/marquee)

### Rating [#rating]

An accessible rating component that allows users to provide star ratings with support for half values, keyboard navigation, and form integration.

<ComponentTabs name="rating-demo" />

[Read the docs](/docs/components/rating)

### QR Code [#qr-code]

A flexible QR code component for generating and displaying QR codes with customization options.

<ComponentTabs name="qr-code-demo" />

[Read the docs](/docs/components/qr-code)

### Hitbox [#hitbox]

A utility component that extends the clickable area of child elements for improved accessibility and user experience.

[Read the docs](/docs/utilities/hitbox)


# October 2025 - Kbd Deprecated
URL: /docs/changelog/2025-10-kbd



[Kbd](/docs/components/radix/kbd) is deprecated and no longer installs. shadcn/ui now ships a [Kbd](https://ui.shadcn.com/docs/components/kbd) component, so use that instead.

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add kbd
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add kbd
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add kbd
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add kbd
    ```
  </CodeBlockTab>
</CodeBlockTabs>

### Migrating [#migrating]

| Dice UI                            | shadcn/ui                                  |
| ---------------------------------- | ------------------------------------------ |
| `Kbd.Root` / `KbdRoot`             | `KbdGroup`                                 |
| `Kbd.Key` / `KbdKey`               | `Kbd`                                      |
| `Kbd.Separator` / `KbdSeparator`   | Text between keys, such as `+`, or nothing |
| `title` on `Kbd.Key`               | Wrap the key in `<abbr title="…">`         |
| `variant` and `size` on `Kbd.Root` | `className`                                |

See the [Kbd](/docs/components/radix/kbd) page for a before and after example.


# November 2025 - New Components
URL: /docs/changelog/2025-11-new-components



We've added ten new components, renamed two, and improved right-to-left support.

* **Scroll Spy**
* **Compare Slider**
* **FPS**
* **Tour**
* **Badge Overflow**
* **Timeline**
* **Time Picker**
* **Stat**
* **Key Value**
* **Stack**

### Scroll Spy [#scroll-spy]

Automatically updates navigation links based on scroll position with support for nested sections and customizable behavior.

<ComponentTabs name="scroll-spy-demo" />

[Read the docs](/docs/components/scroll-spy)

### Compare Slider [#compare-slider]

An interactive before/after comparison slider for comparing two elements side by side.

<ComponentTabs name="compare-slider-demo" />

[Read the docs](/docs/components/compare-slider)

### FPS [#fps]

A real-time frames per second (FPS) counter component for monitoring performance.

<ComponentTabs name="fps-demo" />

[Read the docs](/docs/components/fps)

### Tour [#tour]

A guided tour component that highlights elements and provides step-by-step instructions to help users learn about your application.

<ComponentTabs name="tour-demo" />

[Read the docs](/docs/components/tour)

### Badge Overflow [#badge-overflow]

A component that intelligently manages badge overflow by measuring available space and displaying only what fits with an overflow indicator.

<ComponentTabs name="badge-overflow-demo" />

[Read the docs](/docs/components/badge-overflow)

### Timeline [#timeline]

A flexible timeline component for displaying chronological events with support for different orientations, RTL layouts, and visual states.

<ComponentTabs name="timeline-demo" />

[Read the docs](/docs/components/timeline)

### Time Picker [#time-picker]

An accessible time picker component with inline editing and dropdown selection. Automatically adapts to 12-hour or 24-hour format based on user locale.

<ComponentTabs name="time-picker-demo" />

[Read the docs](/docs/components/time-picker)

### Stat [#stat]

A flexible component for displaying key metrics and statistics with support for trends, indicators, and descriptions.

<ComponentTabs name="stat-demo" />

[Read the docs](/docs/components/stat)

### Key Value [#key-value]

A dynamic input component for managing key-value pairs with paste support and validation.

<ComponentTabs name="key-value-demo" />

[Read the docs](/docs/components/key-value)

### Stack [#stack]

A component that displays items in a stacked layout with hover expansion effects, similar to Sonner toast stacking.

<ComponentTabs name="stack-demo" />

[Read the docs](/docs/components/stack)

### Renamed components [#renamed-components]

* Input Group is now [Segmented Input](/docs/components/segmented-input).
* Avatar is now [Avatar Group](/docs/components/avatar-group). The name Stack now belongs to the new [Stack](/docs/components/stack) component.

### RTL support [#rtl-support]

Components now read direction from Radix's `DirectionProvider` and `useDirection`, so every component shares one global direction context. Wrap your app in [Direction Provider](/docs/utilities/direction-provider) to switch to right-to-left.


# December 2025 - New Components
URL: /docs/changelog/2025-12-new-components



We've added floating action components, dashboard indicators, and a utility for pending states.

* **Action Bar**
* **Speed Dial**
* **Gauge**
* **Status**
* **Pending**

### Action Bar [#action-bar]

A floating action bar that appears at the bottom or top of the viewport to display contextual actions for selected items.

<ComponentTabs name="action-bar-demo" />

[Read the docs](/docs/components/action-bar)

### Speed Dial [#speed-dial]

A floating action button that reveals a set of actions when triggered.

<ComponentTabs name="speed-dial-demo" />

[Read the docs](/docs/components/speed-dial)

### Gauge [#gauge]

A customizable gauge component that displays values on circular or partial arcs, perfect for dashboards, metrics, and KPIs.

<ComponentTabs name="gauge-demo" />

[Read the docs](/docs/components/gauge)

### Status [#status]

A flexible status indicator component with animated ping effect and color variants for displaying system states, user presence, and service health.

<ComponentTabs name="status-demo" />

[Read the docs](/docs/components/status)

### Pending [#pending]

A utility component that disables interactions, maintains keyboard focus, and ensures proper accessibility for buttons, forms, links, switches, and any interactive element while they are pending.

[Read the docs](/docs/utilities/pending)


# January 2026 - New Components
URL: /docs/changelog/2026-01-new-components



We've added four new components.

* **Selection Toolbar**
* **Swap**
* **Responsive Dialog**
* **Phone Input**

### Selection Toolbar [#selection-toolbar]

A floating toolbar that appears on text selection with formatting and utility actions.

<ComponentTabs name="selection-toolbar-demo" />

[Read the docs](/docs/components/selection-toolbar)

### Swap [#swap]

A component that swaps between two states with click or hover activation modes.

<ComponentTabs name="swap-demo" />

[Read the docs](/docs/components/swap)

### Responsive Dialog [#responsive-dialog]

A dialog component that automatically switches between a centered dialog on desktop and a bottom drawer on mobile.

<ComponentTabs name="responsive-dialog-demo" />

[Read the docs](/docs/components/responsive-dialog)

### Phone Input [#phone-input]

An accessible phone input component with automatic country detection and international phone number formatting.

<ComponentTabs name="phone-input-demo" />

[Read the docs](/docs/components/phone-input)


# February 2026 - Unified Radix UI and Multi-Base Architecture
URL: /docs/changelog/2026-02-unified-radix-multi-base



We've shipped several major improvements to Dice UI's component infrastructure and documentation.

### Unified Radix UI Package [#unified-radix-ui-package]

All components have been migrated from individual `@radix-ui/react-*` packages to the unified [`radix-ui`](https://www.radix-ui.com/primitives/docs/overview/getting-started) package. This follows Radix UI's official consolidation effort and simplifies dependency management.

```diff
- import * as SelectPrimitive from "@radix-ui/react-select"
+ import { Select } from "radix-ui"
```

### Optimized Utility Components [#optimized-utility-components]

The `ClientOnly` and `Portal` components have been rewritten using `useSyncExternalStore` for better performance and proper SSR/hydration handling.

**Benefits:**

* No `useState` + `useLayoutEffect` pattern needed
* Proper SSR/Hydration with explicit server vs client snapshots
* No hydration mismatches


# March 2026 - Base UI
URL: /docs/changelog/2026-03-base-ui



Dice UI components now ship for [Base UI](https://base-ui.com) as well as Radix UI. Each component has a Base UI page and a Radix page, and the registry serves a variant for each base.

### Base UI variants [#base-ui-variants]

36 components shipped Base UI variants in this release, built on `@base-ui/react` primitives. Pick the base that matches your project and install the component the same way as before.

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/action-bar
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/action-bar
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/action-bar
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/action-bar
    ```
  </CodeBlockTab>
</CodeBlockTabs>

These components stayed Radix-only at launch:

* [Data Table](/docs/components/data-table) and [Data Grid](/docs/components/data-grid) gained Base UI variants in September 2026.
* [Sortable](/docs/components/sortable) and [Kanban](/docs/components/kanban) gained Base UI variants in September 2026.
* Tags Input, Combobox, Kbd, Checkbox Group, Mention, and Listbox are Radix primitives and remain Radix-only.


# April 2026 - Banner
URL: /docs/changelog/2026-04-banner



We've added a Banner component.

### Banner [#banner]

A notification banner that appears at the top or bottom of the viewport. Supports queuing, priority, and auto-dismiss.

<ComponentTabs name="banner-demo" />

Stack multiple banners in a queue:

<ComponentTabs name="banner-stacked-demo" />

[Read the docs](/docs/components/banner)


# June 2026 - Banner Positioning Strategy
URL: /docs/changelog/2026-06-banner-positioning-strategy



The Banner component now supports multiple positioning strategies, giving you more control over how banners are rendered in your layout.

### Positioning Strategies [#positioning-strategies]

The `Banners` provider accepts a new `strategy` prop with four options:

* **`fixed`** (default): Fixed to the viewport, rendered via portal into `document.body`
* **`absolute`**: Positioned within a container, rendered via portal (container needs `position: relative`)
* **`static`**: Rendered inline, pushes content down
* **`sticky`**: Sticks within a scroll container

```tsx
// Inline banner that pushes content down
<Banners strategy="static">
  <App />
</Banners>

// Sticky banner within a scroll container
<Banners strategy="sticky" side="top">
  <App />
</Banners>
```

`fixed` and `absolute` strategies portal banners out of the DOM tree. `static` and `sticky` render banners inline, either above or below children depending on `side`.

### Other Improvements [#other-improvements]

* Improved type documentation for `Banners` and `Banner` props
* Aligned stacked banner demo action order (primary → secondary) for consistent dismiss targets


# June 2026 - Nova
URL: /docs/changelog/2026-06-nova



Dice UI components now ship in the nova style alongside vega.

### Nova style [#nova-style]

The registry serves `base-nova` and `radix-nova` variants of every component. Projects set up with the nova style get nova-styled Dice UI components with the same install command.

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/banner
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/banner
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/banner
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/banner
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The registry now resolves every official shadcn style. See the [September 2026](/docs/changelog/2026-09-presentation) update.


# September 2026 - Data Table v9
URL: /docs/changelog/2026-09-data-table-v9



[Data Table](/docs/components/data-table) and [Data Grid](/docs/components/data-grid) now ship for both Base UI and Radix, and both run on TanStack Table v9.

Installs no longer include a manual import-path rewrite. The registry writes component, config, and type imports in place.

### Data Table [#data-table]

* **Filtering.** Text, number, range, date, date range, boolean, select, and multi-select, each with its own operators. Compose them as a filter list or a command-style filter menu.
* **Sorting.** Multi-column sorting, persisted in the URL.
* **Pagination.** Manual pagination with a required `pageCount`, plus page size options.
* **URL state.** Page, page size, sort, filters, and join operator stay in the query string through [nuqs](https://nuqs.47ng.com).
* **Columns.** Visibility, ordering, sizing, and pinning. Pin with `start` and `end`.
* **Rows.** Single or multi-row selection, with an action bar for the current selection.
* **Keyboard.** `Ctrl/Cmd + Shift + F` toggles the filter menu, `Ctrl/Cmd + Shift + S` toggles the sort menu, and `Backspace` or `Delete` removes the focused filter or sort.

### Data Grid [#data-grid]

A virtualized, spreadsheet-style grid for large datasets.

* **Editing.** In-place editing across short text, long text, number, URL, checkbox, select, multi-select, date, and file cells.
* **Selection.** Cell and row selection with keyboard and mouse, including shift-range selection.
* **Clipboard.** Copy, cut, and paste, including TSV from Excel or Google Sheets. Paste can add rows when the copied range runs past the grid.
* **Undo and redo.** `useDataGridUndoRedo` tracks cell edits, added rows, and deleted rows. `Ctrl/Cmd + Z` undoes, and `Ctrl/Cmd + Shift + Z` or `Ctrl/Cmd + Y` redoes.
* **Find.** `Ctrl/Cmd + F` searches cells and steps through matches.
* **Filter and sort menus.** Operator-based filters and multi-column sorts, both reorderable.
* **Columns.** Resize, pin (`start` / `end`), hide, and reorder. Double-click a resize handle to fit the column.
* **Rows.** Add and delete through `onRowAdd` and `onRowsDelete`. Row height is short, medium, tall, or extra-tall.
* **Modes.** `readOnly` locks editing. `autoFocus` focuses the first navigable cell, or a specific `{ rowIndex, columnId }`. Direction follows `DirectionProvider`.

### TanStack Table v9 [#tanstack-table-v9]

`useDataTable` and `useDataGrid` are still the public hooks. Under them, tables are created with `useTable` and an explicit feature set: `dataTableFeatures` for the table, `dataGridFeatures` for the grid.

Column definitions, columns, rows, and the table instance take that feature set as the first type argument. Row data must extend `RowData`. Column meta and table meta come from the feature set, so the old `declare module "@tanstack/react-table"` augmentation is gone.

```tsx
import type { ColumnDef } from "@tanstack/react-table";

import type { DataTableFeatures } from "@/lib/data-table-features";

const columns: ColumnDef<DataTableFeatures, Project>[] = [
  // ...
];

const { table } = useDataTable({
  data,
  columns,
  pageCount,
  initialState: {
    columnPinning: { start: ["select"], end: ["actions"] },
  },
});
```

Pinning state is `{ start, end }`. Column visibility state is `ColumnVisibilityState`. Row models are created with `createSortedRowModel`, `createFilteredRowModel`, `createPaginatedRowModel`, and `createFacetedRowModel`, rather than the v8 `get*RowModel` helpers.


# September 2026 - Presentation
URL: /docs/changelog/2026-09-presentation



### Presentation [#presentation]

[Presentation](/docs/components/presentation) is a set of composable primitives for viewing and editing PowerPoint files in the browser. It is built on [`@diceui/pptx`](https://pptx.diceui.com/docs) and ships for both Base UI and Radix.

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/presentation
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/presentation
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/presentation
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/presentation
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```tsx
import {
  Presentation,
  PresentationContent,
  PresentationError,
  PresentationLoading,
  PresentationSelection,
  PresentationSlide,
  PresentationThumbnailList,
  PresentationViewport,
} from "@/components/ui/presentation";
```

`PresentationSelection` is the editing overlay. It supports drag-to-move, resize, inline text, multi-select, and keyboard shortcuts, and it renders only when the file was loaded with `readOnly={false}`.

A companion zoom control is available as `@diceui/presentation-zoom-select`.

### Base UI is the default [#base-ui-is-the-default]

Docs and new installs now default to Base UI with the nova preset (`base-nova`). Radix pages are still published alongside them.

### Styles [#styles]

The registry resolves every official style id: `base` and `radix`, each with vega, nova, maia, lyra, mira, luma, sera, and rhea. Nova itself landed in June.

### Sortable and Kanban [#sortable-and-kanban]

[Sortable](/docs/components/sortable) and [Kanban](/docs/components/kanban) now have Base UI variants.


# October 2026 - Base UI Parity
URL: /docs/changelog/2026-10-base-ui-parity



Base UI and Radix UI now have the same components. Five components that only had Radix versions now have Base UI versions too:

* **Checkbox Group**
* **Combobox**
* **Listbox**
* **Mention**
* **Tags Input**

They're built on the same headless `@diceui/*` packages as their Radix versions, so they share the API, including `asChild` for composition. A `render` prop will follow once these primitives move into a single `@diceui/react` package.

<ComponentTabs name="combobox-demo" />

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/combobox
    ```
  </CodeBlockTab>
</CodeBlockTabs>

[Read the docs](/docs/components/combobox)

### Components and Utilities pages [#components-and-utilities-pages]

The new [Components](/docs/components) and [Utilities](/docs/utilities) pages list everything in one place, with new items marked the same way as in the sidebar. The sidebar is also flatter: components and utilities are grouped under section headings instead of collapsible folders.


# October 2026 - Command Stack
URL: /docs/changelog/2026-10-command-stack



[Command Stack](/docs/components/command-stack) is a searchable command list with nested pages. Use it inline, in a popover, or in a dialog as a command palette.

<ComponentTabs name="command-stack-demo" />

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/command-stack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/command-stack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/command-stack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/command-stack
    ```
  </CodeBlockTab>
</CodeBlockTabs>

[Read the docs](/docs/components/command-stack)


# October 2026 - compose-refs Deprecated
URL: /docs/changelog/2026-10-composition



Dice UI components no longer copy `lib/compose-refs.ts` into your project. They now use the ref helpers their primitives already ship:

* **Base UI** components use `useMergedRefs` from `@base-ui/utils`, which they now list as a dependency.
* **Radix** components use `useComposedRefs` from `radix-ui/internal`. They need nothing new.

The `compose-refs` utility is deprecated as a result. The [Composition](/docs/utilities/composition) page now covers how to compose Dice UI components, and how to build your own parts, with each library's own tools.

### Migrating [#migrating]

Existing components keep working, because your copy of `lib/compose-refs.ts` stays in place. To drop it, reinstall the components, or update the imports yourself:

```tsx title="Base UI"
import { useComposedRefs } from "@/lib/compose-refs"; // [!code --]
import { useMergedRefs } from "@base-ui/utils/useMergedRefs"; // [!code ++]
```

```tsx title="Radix"
import { useComposedRefs } from "@/lib/compose-refs"; // [!code --]
import { useComposedRefs } from "radix-ui/internal"; // [!code ++]
```

Then delete `lib/compose-refs.ts`. `@diceui/compose-refs` still installs for now and will be removed in a future release.


# October 2026 - Data Grid Table Features
URL: /docs/changelog/2026-10-data-grid-table-features



[Data Grid](/docs/components/data-grid) now runs editing, navigation, clipboard, search, and selection as TanStack Table features. Components subscribe only to the state they render, so large grids re-render less.

* **Row actions.** `getDataGridActionsColumn` adds a menu of actions to each row, and `getDataTableActionsColumn` does the same for [Data Table](/docs/components/data-table).
* **Action bar.** The `actionBar` prop on `DataGrid` renders while rows or a range of cells are selected.
* **Cell selection.** Select a range of cells with the mouse or keyboard, and resize or move columns with the keyboard.
* **Editing.** `enableCellEditing` turns editing off for the whole grid or for a single column.

### Migrating [#migrating]

This release has breaking changes. Reinstall all Data Grid files together, because the components, hook, and `lib` files depend on each other.

* **Table meta is gone.** Read state and call actions through the table and cell instead, such as `cell.setValue()`, `cell.startEditing()`, `table.stopEditing()`, and `table.scrollToCell()`. Custom cell variants spread their props onto `DataGridCellWrapper`.
* **`useDataGrid` returns less.** Pass its result to `DataGrid` as before. Values like `searchState`, `focusedCell`, and `virtualItems` now live in table state.
* **`onRowAdd` returns a row id.** Return `{ rowId, columnId? }` to focus the new row.
* **Data slots are renamed** from `grid-*` to `data-grid-*`.

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  onRowAdd: () => {
    const row = { id: crypto.randomUUID() };
    setData((prev) => [...prev, row]);
    return { rowId: row.id, columnId: "name" };
  },
});

return <DataGrid {...dataGridProps} table={table} />;
```

[Read the docs](/docs/components/data-grid)


# October 2026 - Data Table Client Mode
URL: /docs/changelog/2026-10-data-table-client-mode



[Data Table](/docs/components/data-table) and [Data Grid](/docs/components/data-grid) are synced with [tablecn](https://tablecn.com), which is now the source for both components. This release has breaking changes. Read the migration notes before reinstalling.

## Data Table [#data-table]

### Breaking changes [#breaking-changes]

* **Renamed components.** Reinstall under the new registry names. The old names no longer resolve.

  | Before                                           | After                                                           |
  | ------------------------------------------------ | --------------------------------------------------------------- |
  | `DataTableSortList` (`data-table-sort-list`)     | `DataTableSortMenu` (`data-table-sort-menu`)                    |
  | `DataTableFilterList` (`data-table-filter-list`) | `DataTableFilterMenu` (`data-table-filter-menu`)                |
  | `DataTableFilterMenu` (`data-table-filter-menu`) | `DataTableCommandFilterMenu` (`data-table-command-filter-menu`) |

  The name `DataTableFilterMenu` now refers to the filter list. If you used the command-style menu, switch to `DataTableCommandFilterMenu`.

* **One filter model.** `enableAdvancedFilter` is removed from `useDataTable`. `DataTableToolbar` and `DataTableAdvancedToolbar` now read and write the same filters, so you no longer pick a mode in the hook.

* **Per-column URL filters.** Filters no longer live in a single JSON `filters` param. Each filterable column gets its own param, keyed by column id, with the operator as a prefix: `?title=ilike.report&status=in.todo,done`. Filters that use a column's default operator drop the prefix: `?title=report`. Links saved with the old `filters` param stop applying their filters. Sort links in the old JSON format still parse.

* **`queryKeys.filters` is removed.** `queryKeys` now accepts `page`, `perPage`, `sort`, and `joinOperator`.

* **Menu props.** `DataTableFilterMenu` and `DataTableCommandFilterMenu` no longer take `debounceMs`, `throttleMs`, or `shallow`; set those on `useDataTable`. The filter, sort, and view menus accept `disabled` and forward popover content props such as `align`.

* **Renamed types and files.** `lib/parsers` is replaced by `lib/data-table-parsers`, and `dataTableConfig` is replaced by the `FILTER_VARIANTS`, `FILTER_OPERATORS`, and `JOIN_OPERATORS` constants in `lib/data-table-utils`.

  | Before                        | After                         |
  | ----------------------------- | ----------------------------- |
  | `ExtendedColumnFilter<TData>` | `ColumnFilterItem<TColumnId>` |
  | `ExtendedColumnSort<TData>`   | `ColumnSortItem<TColumnId>`   |
  | `Option`                      | `FilterOption`                |
  | `QueryKeys`                   | `DataTableQueryKeys`          |
  | `getFiltersStateParser`       | `getColumnFilterParser`       |

* **Memoized cells.** Rows and cells only re-render when the state they subscribe to changes. A custom checkbox column that reads `row.getIsSelected()` no longer updates when clicked. Use `getDataTableSelectColumn()` from `data-table-select-column`, or wrap selection-dependent cells in `Subscribe`.

* **`Table` props are typed as `ReactTable`.** Components take `table: ReactTable<DataTableFeatures, TData, unknown>`, the type `useDataTable` already returns. Code that passes the hook's `table` straight through doesn't change.

### New [#new]

* **Client mode.** Pass `mode: "client"` to sort, filter, and paginate `data` in the browser, with no `pageCount`. Server mode stays the default and still requires `pageCount`.

  ```tsx
  const { table } = useDataTable({
    mode: "client",
    data,
    columns,
  });
  ```

* **Server helpers.** `getDataTableSearchParams` builds the nuqs parsers from a column config, and `getDataTableQuery` turns the parsed search params into `{ page, perPage, sorting, filters, joinOperator }` for your database query.

  ```ts
  const columnConfigs = {
    title: { variant: "text" },
    status: { variant: "multiSelect" },
    createdAt: { variant: "dateRange" },
  } satisfies DataTableColumnConfigs;

  const searchParams = getDataTableSearchParams({ columnConfigs });
  ```

* **Right-to-left.** Layout, pinning, and menus follow `DirectionProvider`.

* **Accessibility.** Fixes from an accessibility audit, and a `data-slot` on every data table part for styling.

* **Performance.** Cells are memoized, so selection and filter changes skip unchanged cells. A fixed table layout stops columns shifting as data loads.

* **Fixes.** Header menu flicker, multi-sort, row highlights, and action bar actions now scoped to the visible selection.

## Data Grid [#data-grid]

### Breaking changes [#breaking-changes-1]

* **Cells are identified by row id, not row index.** `CellPosition` is now `{ rowId, columnId }`. Pass a stable `getRowId` so ids survive sorting and filtering. This changes:

  * `onRowAdd` returns `{ rowId, columnId }` to focus a cell in the new row.
  * `onRowsDelete` receives `(rows, rowIds)` instead of `(rows, rowIndices)`.
  * `onFilesUpload` and `onFilesDelete` receive `rowId` instead of `rowIndex`.
  * `autoFocus` takes `{ rowId, columnId }`.
  * Custom cells receive `rowId` and `rowHeight` in `DataGridCellProps`. Import the type from `@/lib/data-grid-types`.

  ```tsx
  const onRowAdd = React.useCallback(() => {
    const newRow = { id: generateId() };
    setData((prev) => [...prev, newRow]);

    return { rowId: newRow.id, columnId: "name" }; // [!code highlight]
  }, []);
  ```

* **Row height is table state.** The `rowHeight` option is removed from `useDataGrid`. Set it with `initialState: { rowHeight: "tall" }`, control it with `state.rowHeight` and `onRowHeightChange`, or call `table.setRowHeight`.

* **`onRowAdd` can't return `undefined`.** Return a cell position, or `null` to skip focusing.

### New [#new-1]

* **Cell editing feature.** Editing is a table feature. Turn it off per grid or per column with `enableCellEditing: false`, and read it with `cell.getCanEdit()`, `cell.getIsEditing()`, and `table.setEditingCell`.
* **`onPaste`.** Called with the applied `{ rowId, columnId, value }` updates after a paste, so you can persist them.
* **`enableSingleCellSelection`.** A single click selects the clicked cell.
* **Grid-style keyboard navigation.** Tab and arrow keys move between cells the way a spreadsheet does.
* **Fixes.** The multi-select cell search input.

## Migrating [#migrating]

1. Reinstall the components you use. Replace `data-table-sort-list` and `data-table-filter-list` with `data-table-sort-menu` and `data-table-filter-menu`.
2. Rename imports and types using the tables above.
3. Remove `enableAdvancedFilter` and `queryKeys.filters`.
4. If you parse filters on the server, switch to `getDataTableSearchParams` and `getDataTableQuery`.
5. For Data Grid, replace row indices with row ids in your callbacks and move `rowHeight` into `initialState`.


# October 2026 - Direction Provider Deprecated
URL: /docs/changelog/2026-10-direction-provider



The [Direction Provider](/docs/utilities/direction-provider) utility is deprecated. shadcn/ui now ships a [Direction](https://ui.shadcn.com/docs/components/direction) component with the same `DirectionProvider` and `useDirection` API, and Dice UI components follow it.

### Migrating [#migrating]

Install shadcn/ui's Direction component:

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add direction
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add direction
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add direction
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add direction
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Then update your imports:

```tsx
import { DirectionProvider } from "@/components/direction-provider"; // [!code --]
import { DirectionProvider } from "@/components/ui/direction"; // [!code ++]
```

`@diceui/direction-provider` still installs for now and will be removed in a future release.


# October 2026 - Faceted
URL: /docs/changelog/2026-10-faceted



[Faceted](/docs/components/faceted), the popover behind the [Data Table](/docs/components/data-table) and [Data Grid](/docs/components/data-grid) filters, is now its own component. It supports single or multiple selection, async search, and groups.

<ComponentTabs name="faceted-multiple-demo" />

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/faceted
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/faceted
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/faceted
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/faceted
    ```
  </CodeBlockTab>
</CodeBlockTabs>

[Read the docs](/docs/components/faceted)


# October 2026 - useValueAsRef and useRefWithInit
URL: /docs/changelog/2026-10-ref-hooks



Dice UI components use two small ref hooks. They now share Base UI's names, so call sites read the same in both bases:

| Before       | After            | Base UI                         | Radix                       |
| ------------ | ---------------- | ------------------------------- | --------------------------- |
| `useAsRef`   | `useValueAsRef`  | `@base-ui/utils/useValueAsRef`  | `@diceui/use-value-as-ref`  |
| `useLazyRef` | `useRefWithInit` | `@base-ui/utils/useRefWithInit` | `@diceui/use-ref-with-init` |

Base UI components no longer copy either hook into your project. Radix components install the renamed hooks.

### Migrating [#migrating]

Existing components keep working, because your copies of the old hooks stay in place. To move over, reinstall the components, or update the imports yourself:

```tsx title="Base UI"
import { useAsRef } from "@/hooks/use-as-ref"; // [!code --]
import { useLazyRef } from "@/hooks/use-lazy-ref"; // [!code --]
import { useRefWithInit } from "@base-ui/utils/useRefWithInit"; // [!code ++]
import { useValueAsRef } from "@base-ui/utils/useValueAsRef"; // [!code ++]
```

```tsx title="Radix"
import { useAsRef } from "@/hooks/use-as-ref"; // [!code --]
import { useLazyRef } from "@/hooks/use-lazy-ref"; // [!code --]
import { useRefWithInit } from "@/hooks/use-ref-with-init"; // [!code ++]
import { useValueAsRef } from "@/hooks/use-value-as-ref"; // [!code ++]
```

Then rename the calls. `@diceui/use-as-ref` and `@diceui/use-lazy-ref` still install for now and will be removed in a future release.


# October 2026 - Skip Nav
URL: /docs/changelog/2026-10-skip-nav



We've added a Skip Nav utility and fixed Base UI installs for three utilities.

### Skip Nav [#skip-nav]

A link that lets keyboard and screen reader users skip past repeated navigation to the main content ([WCAG 2.4.1](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html)). It stays hidden until it receives keyboard focus. When focused, it uses `z-index: 100` to stack above sticky headers and other `z-50` layers.

<ComponentTabs name="skip-nav-demo" />

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @diceui/skip-nav
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @diceui/skip-nav
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @diceui/skip-nav
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @diceui/skip-nav
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Render it as the first focusable element and give your main content the exported `MAIN_CONTENT_ID`:

```tsx
import { MAIN_CONTENT_ID, SkipNav } from "@/components/skip-nav";

<body>
  <SkipNav />
  <header>{/* Navigation */}</header>
  <main id={MAIN_CONTENT_ID}>{/* Page content */}</main>
</body>
```

On activation, focus moves to the target, not just the scroll position, so the next <Kbd>Tab</Kbd> continues from the main content. The URL hash doesn't change, so the skip doesn't add a history entry.

[Read the docs](/docs/utilities/skip-nav)

### Base UI utilities [#base-ui-utilities]

[Hitbox](/docs/utilities/hitbox), [Pending](/docs/utilities/pending), and [Visually Hidden](/docs/utilities/visually-hidden) had Base UI docs but no Base UI registry entries, so installing them in a Base UI project failed. They now install for both bases.


# October 2026 - use-isomorphic-layout-effect Deprecated
URL: /docs/changelog/2026-10-use-isomorphic-layout-effect



Dice UI components no longer copy `hooks/use-isomorphic-layout-effect.ts` into your project. They use the hook their primitives already ship:

* **Base UI** components use `useIsoLayoutEffect` from `@base-ui/utils`.
* **Radix** components use `useLayoutEffect` from `radix-ui/internal`.

### Migrating [#migrating]

Existing components keep working, because your copy of the hook stays in place. To drop it, reinstall the components, or update the imports yourself:

```tsx title="Base UI"
import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; // [!code --]
import { useIsoLayoutEffect } from "@base-ui/utils/useIsoLayoutEffect"; // [!code ++]
```

```tsx title="Radix"
import { useIsomorphicLayoutEffect } from "@/hooks/use-isomorphic-layout-effect"; // [!code --]
import { useLayoutEffect } from "radix-ui/internal"; // [!code ++]
```

Then delete `hooks/use-isomorphic-layout-effect.ts`. `@diceui/use-isomorphic-layout-effect` still installs for now and will be removed in a future release.


# Changelog
URL: /docs/changelog



<Changelogs />


# Components
URL: /docs/components



<ComponentList />


# Utilities
URL: /docs/utilities



<ComponentList group="utilities" />


# Action Bar
URL: /docs/components/base/action-bar



<ComponentTabs name="action-bar-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the portal component into your 

        `components/portal.tsx`

         file.
      </Step>

      <ComponentSource name="portal" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="action-bar" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import {
  ActionBar,
  ActionBarSelection,
  ActionBarSeparator,
  ActionBarGroup,
  ActionBarItem,
  ActionBarClose,
} from "@/components/ui/action-bar";

return (
  <ActionBar>
    <ActionBarSelection />
    <ActionBarSeparator />
    <ActionBarGroup>
      <ActionBarItem />
      <ActionBarItem />
    </ActionBarGroup>
    <ActionBarClose />
  </ActionBar>
);
```

## Examples [#examples]

### Position [#position]

Use the `side` and `align` props to control where the action bar appears.

<ComponentTabs name="action-bar-position-demo" />

## API Reference [#api-reference]

### ActionBar [#actionbar]

The root component that controls the visibility and position of the action bar. Has `role="toolbar"` for accessibility.

<AutoTypeTable path="./types/base/action-bar.ts" name="ActionBarProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;bottom&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ActionBarSelection [#actionbarselection]

Displays selection information, typically used to show how many items are selected.

<AutoTypeTable path="./types/base/action-bar.ts" name="ActionBarSelectionProps" />

### ActionBarGroup [#actionbargroup]

A container for action items that implements roving focus management. Items within a group can be navigated using arrow keys, forming a single tab stop. See [Keyboard Interactions](#keyboard-interactions) for full details.

<AutoTypeTable path="./types/base/action-bar.ts" name="ActionBarGroupProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ActionBarItem [#actionbaritem]

An interactive button item within the action bar. When used inside a `Group`, participates in roving focus navigation.

<AutoTypeTable path="./types/base/action-bar.ts" name="ActionBarItemProps" />

### ActionBarClose [#actionbarclose]

A button that closes the action bar by calling the `onOpenChange` callback with `false`. The close button has its own tab stop, separate from the group's roving focus.

<AutoTypeTable path="./types/base/action-bar.ts" name="ActionBarCloseProps" />

### ActionBarSeparator [#actionbarseparator]

A visual separator between action bar items.

<AutoTypeTable path="./types/base/action-bar.ts" name="ActionBarSeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

The action bar follows the [WAI-ARIA Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) for keyboard navigation.

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element (Action Group or Close button).&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the action bar and calls onOpenChange(false).&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves focus to the previous item in the group (horizontal orientation).&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves focus to the previous item in the group (vertical orientation).&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves focus to the next item in the group (horizontal orientation).&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves focus to the next item in the group (vertical orientation).&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves focus to the first item in the group.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves focus to the last item in the group.&#x22;,
  },
]"
/>


# Angle Slider
URL: /docs/components/base/angle-slider



<ComponentTabs name="angle-slider-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Install the direction component from shadcn/ui.
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npx shadcn@latest add direction
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm dlx shadcn@latest add direction
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn dlx shadcn@latest add direction
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun x shadcn@latest add direction
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="angle-slider" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  AngleSlider,
  AngleSliderRange,
  AngleSliderThumb,
  AngleSliderTrack,
  AngleSliderValue,
} from "@/components/ui/angle-slider";

return (
  <AngleSlider>
    <AngleSliderTrack>
      <AngleSliderRange />
    </AngleSliderTrack>
    <AngleSliderThumb />
    <AngleSliderValue />
  </AngleSlider>
)
```

## Examples [#examples]

### **Controlled** State [#controlled-state]

A slider with controlled state management and custom actions.

<ComponentTabs name="angle-slider-controlled-demo" />

### Range Selection [#range-selection]

Use multiple thumbs to create angle ranges with minimum step constraints.

<ComponentTabs name="angle-slider-range-demo" />

### Themes [#themes]

Slider variants with different themes.

<ComponentTabs name="angle-slider-themes-demo" />

### With Form [#with-form]

Integrate the angle slider with form validation and submission.

<ComponentTabs name="angle-slider-form-demo" />

## Theming [#theming]

You can customize the appearance by targeting specific components:

### Track Theming [#track-theming]

Use `[&>[data-slot='angle-slider-track-rail']]` to style the background track:

```tsx
<AngleSliderTrack className="*:data-[slot='angle-slider-track-rail']:stroke-green-100" />
```

### Range Theming [#range-theming]

```tsx
<AngleSliderRange className="stroke-green-500" />
```

### Thumb Theming [#thumb-theming]

```tsx
<AngleSliderThumb className="border-green-500 bg-green-50 ring-green-500/50" />
```

### Value Theming [#value-theming]

```tsx
<AngleSliderValue className="text-green-600 dark:text-green-400" />
```

## API Reference [#api-reference]

### AngleSlider [#angleslider]

The main container component for the angle slider.

<AutoTypeTable path="./types/base/angle-slider.ts" name="AngleSliderProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

### AngleSliderTrack [#angleslidertrack]

The circular track that represents the full range of possible values.

<AutoTypeTable path="./types/base/angle-slider.ts" name="AngleSliderTrackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
  {
    title: &#x22;[data-slot='angle-slider-track-rail']&#x22;,
    value: &#x22;Present on the rail of the track.&#x22;,
  },
]"
/>

### AngleSliderRange [#anglesliderrange]

The portion of the track that represents the selected range.

<AutoTypeTable path="./types/base/angle-slider.ts" name="AngleSliderRangeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

### AngleSliderThumb [#anglesliderthumb]

The draggable handle for selecting values.

<AutoTypeTable path="./types/base/angle-slider.ts" name="AngleSliderThumbProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

### AngleSliderValue [#angleslidervalue]

Displays the current value(s) with customizable formatting.

<AutoTypeTable path="./types/base/angle-slider.ts" name="AngleSliderValueProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

The angle slider component includes comprehensive accessibility features:

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowRight&#x22;],
    description: &#x22;Increase the value by one step.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;, &#x22;ArrowLeft&#x22;],
    description: &#x22;Decrease the value by one step.&#x22;,
  },
  {
    keys: [&#x22;PageUp&#x22;],
    description: &#x22;Increase the value by ten steps.&#x22;,
  },
  {
    keys: [&#x22;PageDown&#x22;],
    description: &#x22;Decrease the value by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Shift + Arrow Keys&#x22;],
    description: &#x22;Increase/decrease the value by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Set the value to the minimum.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Set the value to the maximum.&#x22;,
  },
]"
/>

## Features [#features]

* Optimized for touch interactions on mobile devices
* Smooth dragging experience with proper pointer handling
* Full right-to-left language support
* Comprehensive keyboard navigation and screen reader support
* Angle ranges with minimum step constraints with multiple thumbs
* Controlled and uncontrolled state management


# Avatar Group
URL: /docs/components/base/avatar-group



<ComponentTabs name="avatar-group-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="avatar-group" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import { AvatarGroup } from "@/components/ui/avatar-group";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";

<AvatarGroup>
  <Avatar>
    <AvatarImage src="/tony-hawk.png" />
    <AvatarFallback>TH</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/rodney-mullen.png" />
    <AvatarFallback>RM</AvatarFallback>
  </Avatar>
</AvatarGroup>
```

## Examples [#examples]

### With Truncation [#with-truncation]

Automatically truncate long lists and show overflow indicators with the `max` prop.

<ComponentTabs name="avatar-group-truncation-demo" />

### With RTL [#with-rtl]

Support for right-to-left layouts and vertical RTL stacking.

<ComponentTabs name="avatar-group-rtl-demo" />

### With Icons [#with-icons]

Use the Avatar Group component with icons or other elements beyond avatars.

<ComponentTabs name="avatar-group-icons-demo" />

### Custom Overflow [#custom-overflow]

Customize the overflow indicator with the `renderOverflow` prop.

<ComponentTabs name="avatar-group-custom-overflow-demo" />

## API Reference [#api-reference]

### AvatarGroup [#avatargroup]

The main avatar group container that handles layout and masking of child elements.

<AutoTypeTable path="./types/base/avatar-group.ts" name="AvatarGroupProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>


# Badge Overflow
URL: /docs/components/base/badge-overflow



<ComponentTabs name="badge-overflow-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="badge-overflow" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import { Badge } from "@/components/ui/badge";
import { BadgeOverflow } from "@/components/ui/badge-overflow";

<BadgeOverflow renderBadge={(_, label) => <Badge>{label}</Badge>} />
```

## Usage [#usage]

### With Primitive Arrays [#with-primitive-arrays]

When using primitive arrays (strings, numbers), the `getBadgeLabel` prop is optional. The component will automatically use the item itself as the label.

```tsx
<BadgeOverflow
  items={["React", "TypeScript", "Next.js"]}
  renderBadge={(item, label) => <Badge>{label}</Badge>}
/>
```

### With Object Arrays [#with-object-arrays]

When using object arrays, the `getBadgeLabel` prop is required to extract the label from each item.

```tsx
<BadgeOverflow
  items={[
    { id: 1, name: "React" },
    { id: 2, name: "TypeScript" },
  ]}
  getBadgeLabel={(item) => item.name}
  renderBadge={(item, label) => <Badge>{label}</Badge>}
/>
```

## Examples [#examples]

### Multi-line Overflow [#multi-line-overflow]

Display badges across multiple lines using the `lineCount` prop.

<ComponentTabs name="badge-overflow-multiline-demo" />

### Interactive Tags [#interactive-tags]

Interactive demo showing how to add and remove tags with overflow handling.

<ComponentTabs name="badge-overflow-interactive-demo" />

## API Reference [#api-reference]

### BadgeOverflow [#badgeoverflow]

The component that measures available space and displays badges with overflow indicators.

<AutoTypeTable path="./types/base/badge-overflow.ts" name="BadgeOverflowProps" />

## Features [#features]

### Automatic Width Measurement [#automatic-width-measurement]

The component automatically measures badge widths using DOM measurement and caches results for performance. This ensures accurate overflow calculations without manual configuration.

### Computed Container Styles [#computed-container-styles]

The component automatically extracts container padding, gap, badge height, and overflow badge width from computed styles. This means it adapts seamlessly to your CSS without requiring manual prop configuration.

### Multi-line Support [#multi-line-support]

Control how many lines of badges to display using the `lineCount` prop. The component will intelligently wrap badges across lines while respecting the overflow constraints.

### Custom Rendering [#custom-rendering]

Use `renderBadge` and `renderOverflow` props to fully customize how badges and overflow indicators are rendered, allowing complete control over styling and behavior.

### Performance Optimization [#performance-optimization]

The component renders all badges invisibly to measure their actual widths, then uses those measurements to determine which badges fit within the specified line count. ResizeObserver efficiently responds to container size changes.

## Notes [#notes]

* The component measures actual rendered badges to calculate widths accurately (including icons, custom styling, etc.)
* Container styles (padding, gap, badge height, overflow width) are automatically computed from CSS
* Measurements update automatically when items change or container is resized
* Container must have a defined width for overflow calculations to work


# Banner
URL: /docs/components/base/banner



<ComponentTabs name="banner-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="banner" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import {
  Banner,
  BannerIcon,
  BannerContent,
  BannerTitle,
  BannerDescription,
  BannerActions,
  BannerClose,
} from "@/components/ui/banner";

return (
  <Banner>
    <BannerIcon />
    <BannerContent>
      <BannerTitle />
      <BannerDescription />
    </BannerContent>
    <BannerActions />
    <BannerClose />
  </Banner>
);
```

## Examples [#examples]

### Stacked Banners [#stacked-banners]

Use the `Banners` provider to manage multiple banners with a queue system. Banners can be added imperatively using the `useBanners` hook.

<ComponentTabs name="banner-stacked-demo" />

## API Reference [#api-reference]

### Banners [#banners]

The root provider for managing a queue of banners. Wrap your application or a section to enable banner queuing.

<AutoTypeTable path="./types/base/banner.ts" name="BannersProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;bottom&#x22;],
  },
]"
/>

### Banner [#banner]

An individual banner component. Can be used standalone or within the `Banners` provider.

<AutoTypeTable path="./types/base/banner.ts" name="BannerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### BannerIcon [#bannericon]

Container for the banner's icon.

<AutoTypeTable path="./types/base/banner.ts" name="BannerIconProps" />

### BannerContent [#bannercontent]

Container for the banner's text content (title and description).

<AutoTypeTable path="./types/base/banner.ts" name="BannerContentProps" />

### BannerTitle [#bannertitle]

The banner's title text.

<AutoTypeTable path="./types/base/banner.ts" name="BannerTitleProps" />

### BannerDescription [#bannerdescription]

The banner's description text.

<AutoTypeTable path="./types/base/banner.ts" name="BannerDescriptionProps" />

### BannerActions [#banneractions]

Container for action buttons.

<AutoTypeTable path="./types/base/banner.ts" name="BannerActionsProps" />

### BannerClose [#bannerclose]

A button that dismisses the banner. Uses the shadcn Button component internally.

<AutoTypeTable path="./types/base/banner.ts" name="BannerCloseProps" />

### useBanners [#usebanners]

Hook to access banner queue management within a `Banners` provider.

<AutoTypeTable path="./types/base/banner.ts" name="UseBannersReturn" />

### useBanner [#usebanner]

Hook to access the current banner's context (id, variant, dismissible state, and close handler).

<AutoTypeTable path="./types/base/banner.ts" name="UseBannerReturn" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element within the banner.&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element within the banner.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Activates the focused button.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Activates the focused button.&#x22;,
  },
]"
/>


# Checkbox Group
URL: /docs/components/base/checkbox-group



<ComponentTabs name="checkbox-group-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/checkbox-group
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/checkbox-group
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/checkbox-group
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/checkbox-group
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/checkbox-group
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/checkbox-group
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/checkbox-group
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/checkbox-group
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="checkbox-group" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  CheckboxGroup,
  CheckboxGroupLabel,
  CheckboxGroupList,
  CheckboxGroupItem,
  CheckboxGroupIndicator,
  CheckboxGroupDescription,
} from "@diceui/checkbox-group";

return (
  <CheckboxGroup>
    <CheckboxGroupLabel />
    <CheckboxGroupList>
      <CheckboxGroupItem>
        <CheckboxGroupIndicator />
      </CheckboxGroupItem>
    </CheckboxGroupList>
    <CheckboxGroupDescription>
  </CheckboxGroup>
)
```

## Animated Checkbox [#animated-checkbox]

<Steps>
  <Step>
    Update `tailwind.config.ts` to include the following animation:

    ```ts
    export default {
      theme: {
        extend: {
          keyframes: {
            "stroke-dashoffset": {
              "0%": { strokeDashoffset: "100%" },
              "100%": { strokeDashoffset: "0" },
            },
          },
          animation: {
            "stroke-dashoffset": "stroke-dashoffset 0.2s linear forwards",
          },
        },
      },
    }
    ```
  </Step>

  <Step>
    Copy and paste the `CheckboxGroupIndicator` block from the following example into your project.

    <ComponentTabs name="checkbox-group-animated-demo" />
  </Step>
</Steps>

## Examples [#examples]

### Horizontal Orientation [#horizontal-orientation]

<ComponentTabs name="checkbox-group-horizontal-demo" />

### With Validation [#with-validation]

Validate the group with `onValidate` or `required` prop. Can be used for native form validation.

<ComponentTabs name="checkbox-group-validation-demo" />

### Multi Selection [#multi-selection]

Hold down the `Shift` key to select and deselect multiple checkboxes at once.

<ComponentTabs name="checkbox-group-multi-selection-demo" />

## API Reference [#api-reference]

### CheckboxGroup [#checkboxgroup]

Container for the checkbox group.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

### CheckboxGroupLabel [#checkboxgrouplabel]

Label for the checkbox group.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="LabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### CheckboxGroupList [#checkboxgrouplist]

Container for checkbox items.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="ListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

### CheckboxGroupItem [#checkboxgroupitem]

Individual checkbox item.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;checked&#x22;, &#x22;unchecked&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

### CheckboxGroupIndicator [#checkboxgroupindicator]

Visual indicator for the checkbox state.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="IndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;checked&#x22;, &#x22;unchecked&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### CheckboxGroupDescription [#checkboxgroupdescription]

Optional description text for the checkbox group.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="DescriptionProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

### CheckboxGroupMessage [#checkboxgroupmessage]

Error or validation message for the checkbox group.

<AutoTypeTable path="./types/base/checkbox-group.ts" name="MessageProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Toggles checkbox item.&#x22;
  },
]"
/>


# Circular Progress
URL: /docs/components/base/circular-progress



<ComponentTabs name="circular-progress-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="circular-progress" />

      <Step>
        Add the following CSS animations to your 

        `globals.css`

         file:
      </Step>

      ```css
      @theme {
        --animate-spin-around: spin-around 0.8s linear infinite;

        @keyframes spin-around {
          0% {
            transform: rotate(-90deg);
          }
          100% {
            transform: rotate(270deg);
          }
        }
      }
      ```
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  CircularProgress,
  CircularProgressIndicator,
  CircularProgressTrack,
  CircularProgressRange,
  CircularProgressValueText,
} from "@/components/ui/circular-progress";

return (
  <CircularProgress>
    <CircularProgressIndicator>
      <CircularProgressTrack />
      <CircularProgressRange />
    </CircularProgressIndicator>
    <CircularProgressValueText />
  </CircularProgress>
)
```

Or use the `Combined` component to get all the parts in one.

```tsx
import { CircularProgressCombined } from "@/components/ui/circular-progress";

<CircularProgressCombined />
```

## Examples [#examples]

### Interactive Demo [#interactive-demo]

A circular progress with interactive controls and simulated upload progress.

<ComponentTabs name="circular-progress-interactive-demo" />

### Colors [#colors]

Different color themes using Tailwind CSS stroke and text utilities to customize the track, range, and value text colors.

<ComponentTabs name="circular-progress-colors-demo" />

## Theming [#theming]

The circular progress component uses CSS `currentColor` for stroke colors, making it easy to theme using Tailwind's text or stroke utilities:

### Track Theming [#track-theming]

```tsx
<CircularProgressTrack className="text-green-200 dark:text-green-900" />
```

### Range Theming [#range-theming]

```tsx
<CircularProgressRange className="text-green-500" />
```

### Value Text Theming [#value-text-theming]

```tsx
<CircularProgressValueText className="text-green-700 dark:text-green-300" />
```

### Custom Stroke Styles [#custom-stroke-styles]

You can also use Tailwind's stroke utilities directly:

```tsx
<CircularProgressTrack className="stroke-blue-200" />
<CircularProgressRange className="stroke-blue-500" />
```

## API Reference [#api-reference]

### CircularProgress [#circularprogress]

The main container component for the circular progress.

<AutoTypeTable path="./types/base/circular-progress.ts" name="CircularProgressProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current progress value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum progress value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum progress value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### CircularProgressIndicator [#circularprogressindicator]

The SVG container that holds the circular progress tracks and ranges.

<AutoTypeTable path="./types/base/circular-progress.ts" name="CircularProgressIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current progress value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum progress value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum progress value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### CircularProgressTrack [#circularprogresstrack]

The background circle that represents the full range of possible values.

<AutoTypeTable path="./types/base/circular-progress.ts" name="CircularProgressTrackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### CircularProgressRange [#circularprogressrange]

The portion of the circle that represents the current progress value.

<AutoTypeTable path="./types/base/circular-progress.ts" name="CircularProgressRangeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current progress value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum progress value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum progress value.&#x22;,
  },
]"
/>

### CircularProgressValueText [#circularprogressvaluetext]

The text element that displays the current progress value or custom content.

<AutoTypeTable path="./types/base/circular-progress.ts" name="CircularProgressValueTextProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### CircularProgressCombined [#circularprogresscombined]

The combined component that includes all the parts.

<AutoTypeTable path="./types/base/circular-progress.ts" name="CircularProgressProps" />

## Accessibility [#accessibility]

### Screen Reader Support [#screen-reader-support]

* Uses the `progressbar` role for proper screen reader identification
* Provides `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` attributes
* Supports indeterminate state by omitting `aria-valuenow` when value is null

## Notes [#notes]

* The component automatically handles indeterminate states when `value` is `null` or `undefined`
* Progress values are automatically clamped to the valid range between `min` and `max`
* Invalid `max` or `value` props will log console errors and use fallback values
* The indeterminate animation uses CSS custom properties and can be customized via the `--animate-spin-around` variable
* All stroke colors use `currentColor` by default, making them responsive to text color changes


# Color Picker
URL: /docs/components/base/color-picker



<ComponentTabs name="color-picker-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="color-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ColorPicker,
  ColorPickerAlphaSlider,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerEyeDropper,
  ColorPickerFormatSelect,
  ColorPickerHueSlider,
  ColorPickerInput,
  ColorPickerSwatch,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

return (
  <ColorPicker>
    <ColorPickerTrigger>
      <ColorPickerSwatch />
    </ColorPickerTrigger>
    <ColorPickerContent>
      <ColorPickerArea />
      <ColorPickerEyeDropper />
      <ColorPickerHueSlider />
      <ColorPickerAlphaSlider />
      <ColorPickerFormatSelect />
      <ColorPickerInput />
    </ColorPickerContent>
  </ColorPicker>
)
```

## Examples [#examples]

### Inline Color Picker [#inline-color-picker]

Use the `inline` prop to render the color picker inline instead of in a popover.

<ComponentTabs name="color-picker-inline-demo" />

### Controlled State [#controlled-state]

A color picker with controlled state management.

<ComponentTabs name="color-picker-controlled-demo" />

### With Form [#with-form]

A color picker with form integration.

<ComponentTabs name="color-picker-form-demo" />

## API Reference [#api-reference]

### ColorPicker [#colorpicker]

The main container component for the color picker.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerProps" />

### ColorPickerTrigger [#colorpickertrigger]

The trigger button that opens the color picker popover.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerTriggerProps" />

### ColorPickerContent [#colorpickercontent]

The content container for the color picker components.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerContentProps" />

### ColorPickerArea [#colorpickerarea]

The 2D color area for selecting hue and saturation.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerAreaProps" />

### ColorPickerSwatch [#colorpickerswatch]

A color swatch that displays the current color.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerSwatchProps" />

### ColorPickerHueSlider [#colorpickerhueslider]

A slider for adjusting the hue value of the color.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerHueSliderProps" />

### ColorPickerAlphaSlider [#colorpickeralphaslider]

A slider for adjusting the alpha (transparency) value of the color.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerAlphaSliderProps" />

### ColorPickerEyeDropper [#colorpickereyedropper]

A button that activates the browser's native eye dropper tool to pick colors from the screen.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerEyeDropperProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the component is disabled.&#x22;,
  },
]"
/>

**Note:** The EyeDropper component only renders when the browser supports the native EyeDropper API. It will return `null` in unsupported browsers.

### ColorPickerFormatSelect [#colorpickerformatselect]

A select dropdown for choosing the color format (hex, rgb, hsl, hsb).

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerFormatSelectProps" />

### ColorPickerInput [#colorpickerinput]

An input field that displays and allows editing of the color value in the selected format.

<AutoTypeTable path="./types/base/color-picker.ts" name="ColorPickerInputProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Opens the color picker when focus is on the trigger.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the color picker and moves focus to the trigger.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowDown&#x22;, &#x22;ArrowLeft&#x22;, &#x22;ArrowRight&#x22;],
    description: &#x22;Adjusts the color value when focus is on sliders or the color area.&#x22;,
  },
]"
/>

## Browser Support [#browser-support]

### EyeDropper API [#eyedropper-api]

The EyeDropper component requires browser support for the native EyeDropper API:

* **Chrome/Edge**: Supported from version 95+
* **Firefox**: Not supported
* **Safari**: Not supported

The component gracefully handles unsupported browsers by not rendering the eye dropper button.

## Color Formats [#color-formats]

The color picker supports the following color formats:

* **HEX**: Hexadecimal color notation (e.g., `#3b82f6`)
* **RGB**: Red, Green, Blue color notation (e.g., `rgb(59, 130, 246)`)
* **HSL**: Hue, Saturation, Lightness color notation (e.g., `hsl(217, 91%, 60%)`)
* **HSB**: Hue, Saturation, Brightness color notation (e.g., `hsb(217, 76%, 96%)`)

All formats support alpha channel for transparency when not using the `withoutAlpha` prop.


# Color Swatch
URL: /docs/components/base/color-swatch



<ComponentTabs name="color-swatch-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="color-swatch" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

Import the component and use it to display color values.

```tsx
import { ColorSwatch } from "@/components/ui/color-swatch";

<ColorSwatch value="#3b82f6" />
```

## Examples [#examples]

### Different Sizes [#different-sizes]

The color swatch component supports three different sizes: `sm`, `default`, and `lg`.

<ComponentTabs name="color-swatch-sizes-demo" />

### Transparency Support [#transparency-support]

The color swatch automatically detects transparent colors and displays them with a checkerboard background pattern.

<ComponentTabs name="color-swatch-transparency-demo" />

## API Reference [#api-reference]

### ColorSwatch [#colorswatch]

A color swatch component that displays a color value with optional transparency support.

<AutoTypeTable path="./types/base/color-swatch.ts" name="ColorSwatchProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the component is disabled.&#x22;,
  },
  {
    title: &#x22;[data-slot]&#x22;,
    value: &#x22;Always set to 'color-swatch' for identification.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

The color swatch component includes proper accessibility features:

* **ARIA Label**: Automatically generates descriptive `aria-label` text based on the color value
* **Role**: Uses `role="img"` to indicate it's an image representation of a color
* **Disabled State**: Properly handles disabled state with appropriate visual and interaction changes

### Screen Reader Support [#screen-reader-support]

* When a color value is provided, the `aria-label` reads "Color swatch: \[color-value]"
* When no color is selected, the `aria-label` reads "No color selected"

## Color Format Support [#color-format-support]

The color swatch component supports various color formats:

* **HEX**: `#3b82f6`
* **RGB**: `rgb(59, 130, 246)`
* **RGBA**: `rgba(59, 130, 246, 0.5)`
* **HSL**: `hsl(217, 91%, 60%)`
* **HSLA**: `hsla(217, 91%, 60%, 0.5)`
* **Named Colors**: `blue`, `red`, etc.

## Transparency Detection [#transparency-detection]

The component automatically detects transparent colors by checking for:

* `rgba()` or `hsla()` function notation
* RGB/HSL with 4 values (including alpha)
* Any color format that includes transparency information

When transparency is detected, a checkerboard pattern is displayed behind the color to show the transparency effect. Use the `withoutTransparency` prop to disable this behavior.


# Combobox
URL: /docs/components/base/combobox



<ComponentTabs name="combobox-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/combobox
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/combobox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/combobox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/combobox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/combobox
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="combobox" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Combobox,
  ComboboxLabel,
  ComboboxAnchor,
  ComboboxBadgeList,
  ComboboxBadgeItem,
  ComboboxBadgeItemDelete,
  ComboboxInput,
  ComboboxTrigger,
  ComboboxCancel,
  ComboboxPortal,
  ComboboxContent,
  ComboboxArrow,
  ComboboxLoading,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxItem,
  ComboboxItemText,
  ComboboxItemIndicator,
  ComboboxSeparator,
} from "@diceui/combobox";

return (
  <Combobox>
    <ComboboxLabel />
    <ComboboxAnchor>
      <ComboboxBadgeList>
        <ComboboxBadgeItem>
          <ComboboxBadgeItemDelete />
        </ComboboxBadgeItem>
      </ComboboxBadgeList>
      <ComboboxInput />
      <ComboboxTrigger />
      <ComboboxCancel />
    </ComboboxAnchor>
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxArrow />
        <ComboboxLoading />
        <ComboboxEmpty />
        <ComboboxGroup>
          <ComboboxGroupLabel />
          <ComboboxItem>
            <ComboboxItemText />
            <ComboboxItemIndicator />
          </ComboboxItem>
        </ComboboxGroup>
        <ComboboxSeparator />
      </ComboboxContent>
    </ComboboxPortal>
  </Combobox>
)
```

## Examples [#examples]

### With Groups [#with-groups]

<ComponentTabs name="combobox-groups-demo" />

### With Multiple Selection [#with-multiple-selection]

<ComponentTabs name="combobox-multiple-demo" />

### With Custom Filter [#with-custom-filter]

<ComponentTabs name="combobox-custom-filter-demo" />

### With Debounce [#with-debounce]

<ComponentTabs name="combobox-debounced-demo" />

### With Virtualization [#with-virtualization]

<ComponentTabs name="combobox-virtualized-demo" />

### With Tags Input [#with-tags-input]

<ComponentTabs name="combobox-tags-demo" />

## API Reference [#api-reference]

### Combobox [#combobox]

The container for all combobox parts.

<AutoTypeTable path="./types/base/combobox.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
]"
/>

### ComboboxLabel [#comboboxlabel]

An accessible label that describes the combobox. Associates with the input element for screen readers.

<AutoTypeTable path="./types/base/combobox.ts" name="LabelProps" />

### ComboboxAnchor [#comboboxanchor]

A wrapper element that positions the combobox popover relative to the input and trigger. Provides the reference point for popover positioning.

<AutoTypeTable path="./types/base/combobox.ts" name="AnchorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-anchor]&#x22;,
    value: &#x22;Present when the anchor is present&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-focused]&#x22;,
    value: &#x22;Present when the anchor is focused&#x22;,
  },
]"
/>

### ComboboxTrigger [#comboboxtrigger]

A button that toggles the combobox popover. Handles focus management and keyboard interactions for opening/closing the popover.

<AutoTypeTable path="./types/base/combobox.ts" name="TriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
]"
/>

### ComboboxInput [#comboboxinput]

The text input field that users can type into to filter options.

<AutoTypeTable path="./types/base/combobox.ts" name="InputProps" />

### ComboboxBadgeList [#comboboxbadgelist]

A container for displaying selected items as badges in a multi-select combobox.

<AutoTypeTable path="./types/base/combobox.ts" name="BadgeListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ComboboxBadgeItem [#comboboxbadgeitem]

An individual badge representing a selected item in a multi-select combobox.

<AutoTypeTable path="./types/base/combobox.ts" name="BadgeItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the badge is disabled&#x22;,
  },
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the badge is highlighted&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ComboboxBadgeItemDelete [#comboboxbadgeitemdelete]

A button to remove a selected item from the multi-select combobox.

<AutoTypeTable path="./types/base/combobox.ts" name="BadgeItemDeleteProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the parent badge is disabled&#x22;,
  },
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the parent badge is highlighted&#x22;,
  },
]"
/>

### ComboboxCancel [#comboboxcancel]

A button that clears the input value and resets the filter.

<AutoTypeTable path="./types/base/combobox.ts" name="CancelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
]"
/>

### ComboboxPortal [#comboboxportal]

A portal for rendering the combobox content outside of its DOM hierarchy.

<AutoTypeTable path="./types/base/combobox.ts" name="PortalProps" />

### ComboboxContent [#comboboxcontent]

The popover container for combobox items. Positions the combobox popover relative to the anchor.

<AutoTypeTable path="./types/base/combobox.ts" name="ContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--dice-transform-origin&#x22;,
    description: &#x22;Transform origin for anchor positioning.&#x22;,
  },
  {
    title: &#x22;--dice-anchor-width&#x22;,
    description: &#x22;Width of the anchor element.&#x22;,
  },
  {
    title: &#x22;--dice-anchor-height&#x22;,
    description: &#x22;Height of the anchor element.&#x22;,
  },
  {
    title: &#x22;--dice-available-width&#x22;,
    description: &#x22;Available width in the viewport for the popover element.&#x22;,
  },
  {
    title: &#x22;--dice-available-height&#x22;,
    description: &#x22;Available height in the viewport for the popover element.&#x22;,
  },
]"
/>

### ComboboxArrow [#comboboxarrow]

A visual arrow element that points to the anchor.

<AutoTypeTable path="./types/base/combobox.ts" name="ArrowProps" />

### ComboboxLoading [#comboboxloading]

A loading indicator for asynchronous filtering operations.

<AutoTypeTable path="./types/base/combobox.ts" name="LoadingProps" />

### ComboboxEmpty [#comboboxempty]

A placeholder component displayed when no options match the current filter.

<AutoTypeTable path="./types/base/combobox.ts" name="EmptyProps" />

### ComboboxGroup [#comboboxgroup]

A container for logically grouping related options.

<AutoTypeTable path="./types/base/combobox.ts" name="GroupProps" />

### ComboboxGroupLabel [#comboboxgrouplabel]

A label that describes a group of options.

<AutoTypeTable path="./types/base/combobox.ts" name="GroupLabelProps" />

### ComboboxItem [#comboboxitem]

An interactive item in the combobox list.

<AutoTypeTable path="./types/base/combobox.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the item is highlighted&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;checked&#x22;, &#x22;unchecked&#x22;],
  },
]"
/>

### ComboboxItemText [#comboboxitemtext]

The textual content of an item.

<AutoTypeTable path="./types/base/combobox.ts" name="ItemTextProps" />

### ComboboxItemIndicator [#comboboxitemindicator]

A visual indicator for selected options.

<AutoTypeTable path="./types/base/combobox.ts" name="ItemIndicatorProps" />

### ComboboxSeparator [#comboboxseparator]

A visual divider for separating options or groups.

<AutoTypeTable path="./types/base/combobox.ts" name="SeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When open, selects the highlighted option. When a badge is highlighted in multiple mode, removes the badge.&#x22;
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;When open, highlights the previous option.&#x22;
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;When open, highlights the next option.&#x22;
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;In multiple mode: When cursor is at start of input, closes the menu and highlights the last badge. When a badge is highlighted, moves highlight to previous badge.&#x22;
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;In multiple mode: When a badge is highlighted, moves highlight to next badge. If on last badge, removes highlight and focuses input.&#x22;
  },
  {
    keys: [&#x22;Backspace&#x22;, &#x22;Delete&#x22;],
    description: &#x22;In multiple mode: When input is empty, removes the last badge. When a badge is highlighted, removes the highlighted badge.&#x22;
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;When open, highlights the first option.&#x22;
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;When open, highlights the last option.&#x22;
  },
  {
    keys: [&#x22;PageUp&#x22;],
    description: &#x22;When open and modal is enabled, highlights the previous option.&#x22;
  },
  {
    keys: [&#x22;PageDown&#x22;],
    description: &#x22;When open and modal is enabled, highlights the next option.&#x22;
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the combobox popover, returns focus to the input, and resets or restores the input value.&#x22;
  },
]"
/>


# Command Stack
URL: /docs/components/base/command-stack



<ComponentTabs name="command-stack-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the command component from shadcn/ui.
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npx shadcn@latest add command
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm dlx shadcn@latest add command
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn dlx shadcn@latest add command
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun x shadcn@latest add command
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="command-stack" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  CommandStack,
  CommandStackBreadcrumb,
  CommandStackEmpty,
  CommandStackGroup,
  CommandStackInput,
  CommandStackItem,
  CommandStackList,
  CommandStackPage,
  CommandStackShortcut,
} from "@/components/ui/command-stack";

return (
  <CommandStack>
    <CommandStackBreadcrumb />
    <CommandStackInput />
    <CommandStackList>
      <CommandStackEmpty />
      <CommandStackPage value="root">
        <CommandStackGroup>
          <CommandStackItem page="projects">
            <CommandStackShortcut />
          </CommandStackItem>
        </CommandStackGroup>
      </CommandStackPage>
      <CommandStackPage value="projects">
        <CommandStackItem />
      </CommandStackPage>
    </CommandStackList>
  </CommandStack>
)
```

## Examples [#examples]

### Popover [#popover]

Put the stack in a popover for nested menus, such as a filter menu where each filter opens its options. Set `selectionMode` on a page to make its items toggleable, and control the selection with `value` and `onValueChange`. The stack goes back to the root page whenever the popover closes.

<ComponentTabs name="command-stack-popover-demo" />

### Command Palette [#command-palette]

Render the stack inside `CommandDialog` to build a command palette. This example uses the `line` input and opens with <Kbd>⌘ J</Kbd>, since <Kbd>⌘ K</Kbd> opens the docs search.

<ComponentTabs name="command-stack-dialog-demo" />

### Workspace [#workspace]

A workspace menu that nests pages several levels deep, from members to a member's role. Items can show avatars, descriptions and trailing details.

<ComponentTabs name="command-stack-workspace-demo" />

### Async [#async]

Load a page's items when it opens. `useCommandStack` gives access to the active page, and `CommandStackLoading` hides the empty state while items load.

<ComponentTabs name="command-stack-async-demo" />

## API Reference [#api-reference]

### CommandStack [#commandstack]

The root component. It keeps the stack of open pages and the search value, and clears the search whenever the page changes.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackProps" />

### CommandStackBreadcrumb [#commandstackbreadcrumb]

Shows the open pages, using each page's `label`.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackBreadcrumbProps" />

### CommandStackInput [#commandstackinput]

The search input. Pressing <Kbd>Backspace</Kbd> while it's empty goes back a page. Set `variant="line"` for a plain row with a divider below it.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackInputProps" />

### CommandStackList [#commandstacklist]

The scrollable list of pages, groups and items.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackListProps" />

### CommandStackEmpty [#commandstackempty]

Shown when no items match the search. It stays hidden while a `CommandStackLoading` is rendered.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackEmptyProps" />

### CommandStackLoading [#commandstackloading]

Shown while a page's items load.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackLoadingProps" />

### CommandStackPage [#commandstackpage]

A page of items. Only the active page renders its children.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackPageProps" />

### CommandStackGroup [#commandstackgroup]

A group of items with an optional heading.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackGroupProps" />

### CommandStackItem [#commandstackitem]

A selectable item. Set `page` to open a page when it's selected, which also shows a chevron, or give it a `value` on a page with a `selectionMode` to make it toggleable.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackItemProps" />

### CommandStackShortcut [#commandstackshortcut]

A keyboard shortcut hint shown at the end of an item.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackShortcutProps" />

### CommandStackSeparator [#commandstackseparator]

A line between groups.

<AutoTypeTable path="./types/base/command-stack.ts" name="CommandStackSeparatorProps" />

### useCommandStack [#usecommandstack]

Reads and changes the stack's pages from any component inside it. It returns `pages`, `activePage`, `search`, `value`, `pushPage(page)`, `popPage()`, `setPages(pages)` and `setValue(value)`.

```tsx
import { useCommandStack } from "@/components/ui/command-stack";

function OpenSettings() {
  const { pushPage } = useCommandStack();

  return (
    <CommandStackItem onSelect={() => pushPage("settings")}>
      Settings
    </CommandStackItem>
  );
}
```

## Accessibility [#accessibility]

The input keeps focus while you move between pages. On a nested page, the input shows a back button labelled "Back". The breadcrumb is a labelled navigation landmark that marks the current page, and opening a page announces its label to screen readers.

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowDown&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves the highlight to the next or previous item.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;, &#x22;End&#x22;],
    description: &#x22;Moves the highlight to the first or last item.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Selects the highlighted item, opening its page if it has one.&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;When the input is empty, goes back to the previous page.&#x22;,
  },
]"
/>


# Compare Slider
URL: /docs/components/base/compare-slider



<ComponentTabs name="compare-slider-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="compare-slider" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  CompareSlider,
  CompareSliderBefore,
  CompareSliderAfter,
  CompareSliderHandle,
} from "@/components/ui/compare-slider";

return (
  <CompareSlider>
    <CompareSliderBefore />
    <CompareSliderAfter />
    <CompareSliderHandle />
  </CompareSlider>
)
```

## Examples [#examples]

### Controlled State [#controlled-state]

A compare slider with external controls for the slider position.

<ComponentTabs name="compare-slider-controlled-demo" />

### Vertical Orientation [#vertical-orientation]

A compare slider with vertical orientation, perfect for comparing tall images or content.

<ComponentTabs name="compare-slider-vertical-demo" />

### Customization [#customization]

Compare slider with custom handle, labels, and vertical orientation.

<ComponentTabs name="compare-slider-customization-demo" />

## API Reference [#api-reference]

### CompareSlider [#compareslider]

The root container for the compare slider component.

<AutoTypeTable path="./types/base/compare-slider.ts" name="CompareSliderProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderBefore [#comparesliderbefore]

The container for the "before" content that appears on the left (or top in vertical mode).

<AutoTypeTable path="./types/base/compare-slider.ts" name="CompareSliderBeforeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderAfter [#comparesliderafter]

The container for the "after" content that appears on the right (or bottom in vertical mode).

<AutoTypeTable path="./types/base/compare-slider.ts" name="CompareSliderAfterProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderHandle [#comparesliderhandle]

The draggable handle that controls the comparison position.

<AutoTypeTable path="./types/base/compare-slider.ts" name="CompareSliderHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderLabel [#comparesliderlabel]

Custom labels that can be positioned on either side of the comparison.

<AutoTypeTable path="./types/base/compare-slider.ts" name="CompareSliderLabelProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the slider.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus away from the slider to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves the slider position left (or up in vertical mode) by the step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;, &#x22;ArrowDown&#x22;],
    description: &#x22;Moves the slider position right (or down in vertical mode) by the step amount.&#x22;,
  },
  {
    keys: [&#x22;PageUp&#x22;],
    description: &#x22;Moves the slider position left (or up in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;PageDown&#x22;],
    description: &#x22;Moves the slider position right (or down in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowLeft&#x22;, &#x22;Shift + ArrowUp&#x22;],
    description: &#x22;Moves the slider position left (or up in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowRight&#x22;, &#x22;Shift + ArrowDown&#x22;],
    description: &#x22;Moves the slider position right (or down in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves the slider to the minimum position (0%).&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves the slider to the maximum position (100%).&#x22;,
  },
]"
/>

### Mouse and Touch Interactions [#mouse-and-touch-interactions]

* **Drag**: Click and drag the handle to adjust the comparison position
* **Click**: Click anywhere on the slider container to jump to that position
* **Touch**: Full touch support for mobile devices

## Advanced Usage [#advanced-usage]

### Custom Content Types [#custom-content-types]

The compare slider works with any React content, not just images:

```tsx
<CompareSlider>
  <CompareSliderBefore>
    <div className="flex items-center justify-center bg-blue-500">
      <p>Old Design</p>
    </div>
  </CompareSliderBefore>
  <CompareSliderAfter>
    <div className="flex items-center justify-center bg-green-500">
      <p>New Design</p>
    </div>
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

### Vertical Orientation [#vertical-orientation-1]

Use vertical orientation for comparing content that works better in a vertical layout. The slider handle moves vertically, and the "before" content appears on top while "after" content appears on bottom.

```tsx
<CompareSlider orientation="vertical" className="h-[600px]">
  <CompareSliderBefore>
    {/* Top content */}
  </CompareSliderBefore>
  <CompareSliderAfter>
    {/* Bottom content */}
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

See the [Vertical Orientation example](#vertical-orientation) for a complete demo.

### Custom Labels [#custom-labels]

Add custom labels to identify each side:

```tsx
<CompareSlider>
  <CompareSliderBefore label="Original">
    {/* Content */}
  </CompareSliderBefore>
  <CompareSliderAfter label="Enhanced">
    {/* Content */}
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

Or use the `CompareSliderLabel` component for more control:

```tsx
<CompareSlider>
  <CompareSliderBefore>
    {/* Content */}
  </CompareSliderBefore>
  <CompareSliderAfter>
    {/* Content */}
  </CompareSliderAfter>
  <CompareSliderHandle />
  <CompareSliderLabel side="before" className="bg-blue-500/90 text-white">
    Original
  </CompareSliderLabel>
  <CompareSliderLabel side="after" className="bg-green-500/90 text-white">
    Enhanced
  </CompareSliderLabel>
</CompareSlider>
```

## Browser Support [#browser-support]

### Core Features [#core-features]

All core comparison features work in modern browsers:

* **Chrome/Edge**: Full support
* **Firefox**: Full support
* **Safari**: Full support (iOS 13+)

### Touch Gestures [#touch-gestures]

Touch interactions require modern touch APIs:

* **iOS Safari**: Supported from iOS 13+
* **Chrome Mobile**: Full support
* **Firefox Mobile**: Full support

## Troubleshooting [#troubleshooting]

### Content Overflow [#content-overflow]

Ensure your content is properly contained within the slider:

```tsx
<CompareSlider className="h-[400px] overflow-hidden">
  <CompareSliderBefore>
    <img className="size-full object-cover" src="..." />
  </CompareSliderBefore>
  {/* ... */}
</CompareSlider>
```

### Performance with Large Images [#performance-with-large-images]

For large images, consider:

1. Using optimized image formats (WebP, AVIF)
2. Lazy loading images
3. Using appropriate image sizes for the display size
4. Implementing image preloading for smoother transitions

### Mobile Considerations [#mobile-considerations]

On mobile devices:

* Ensure touch targets are adequately sized
* Test on various screen sizes
* Consider using vertical orientation for better mobile UX
* Ensure content is responsive and scales appropriately

## Credits [#credits]

* [Samuel Ferrara](https://unsplash.com/@samferrara?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/photos/aerial-photo-of-foggy-mountains-1527pjeb6jg?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText) - For the demo images used in the examples.


# Cropper
URL: /docs/components/base/cropper



<ComponentTabs name="cropper-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="cropper" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Cropper,
  CropperArea,
  CropperImage,
  CropperVideo,
} from "@/components/ui/cropper";

return (
  <Cropper>
    <CropperImage src="/image.jpg" alt="Image to crop" />
    <CropperArea />
  </Cropper>
)
```

## Examples [#examples]

### Controlled State [#controlled-state]

A cropper with external controls for zoom, rotation, and crop position.

<ComponentTabs name="cropper-controlled-demo" />

### With File Upload [#with-file-upload]

A cropper integrated with the [FileUpload](https://diceui.com/docs/components/radix/file-upload) component for uploading and cropping images.

<ComponentTabs name="cropper-file-upload-demo" />

### Different Shapes [#different-shapes]

A cropper with different shapes and configuration options.

<ComponentTabs name="cropper-shapes-demo" />

### Video Cropping [#video-cropping]

A cropper that works with video content.

<ComponentTabs name="cropper-video-demo" />

## API Reference [#api-reference]

### Cropper [#cropper]

The root container for the cropper component.

<AutoTypeTable path="./types/base/cropper.ts" name="CropperProps" />

### CropperImage [#cropperimage]

The image element to be cropped.

<AutoTypeTable path="./types/base/cropper.ts" name="CropperImageProps" />

### CropperVideo [#croppervideo]

The video element to be cropped.

<AutoTypeTable path="./types/base/cropper.ts" name="CropperVideoProps" />

### CropperArea [#cropperarea]

The crop area overlay that shows the selected region.

<AutoTypeTable path="./types/base/cropper.ts" name="CropperAreaProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the cropper content.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves the crop area up by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves the crop area down by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves the crop area left by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves the crop area right by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;Shift + Arrow Keys&#x22;],
    description: &#x22;Moves the crop area with finer precision (20% of keyboard step).&#x22;,
  },
]"
/>

### Mouse and Touch Interactions [#mouse-and-touch-interactions]

* **Drag**: Pan the media within the crop area
* **Scroll/Wheel**: Zoom in and out (can be disabled with `preventScrollZoom`)
* **Pinch**: Zoom and rotate on touch devices
* **Two-finger drag**: Pan while maintaining pinch zoom

## Advanced Usage [#advanced-usage]

### Custom Crop Calculations [#custom-crop-calculations]

You can use the crop data from `onCropComplete` to perform server-side cropping:

```tsx
const onCropComplete = (croppedArea, croppedAreaPixels) => {
  // croppedArea contains percentages (0-100)
  // croppedAreaPixels contains actual pixel coordinates
  
  // Send to server for processing
  cropImage({
    x: croppedAreaPixels.x,
    y: croppedAreaPixels.y,
    width: croppedAreaPixels.width,
    height: croppedAreaPixels.height,
  });
};
```

### Performance Optimization [#performance-optimization]

The cropper includes several performance optimizations:

* **LRU Caching**: Frequently used calculations are cached
* **RAF Throttling**: UI updates are throttled using requestAnimationFrame
* **Quantization**: Values are quantized to reduce cache misses
* **Lazy Computation**: Expensive calculations are deferred when possible

### Object Fit Modes [#object-fit-modes]

The cropper supports different object fit modes:

* **contain**: Media fits entirely within the container (default)
* **cover**: Media covers the entire container, may be cropped
* **horizontal-cover**: Media width matches container width
* **vertical-cover**: Media height matches container height

## Browser Support [#browser-support]

### Core Features [#core-features]

All core cropping features work in modern browsers:

* **Chrome/Edge**: Full support
* **Firefox**: Full support
* **Safari**: Full support (iOS 13+)

### Touch Gestures [#touch-gestures]

Multi-touch gestures require modern touch APIs:

* **iOS Safari**: Supported from iOS 13+
* **Chrome Mobile**: Full support
* **Firefox Mobile**: Basic touch support

### Video Support [#video-support]

Video cropping requires modern video APIs:

* **Chrome/Edge**: Full support for all video formats
* **Firefox**: Full support with some codec limitations
* **Safari**: Full support with H.264/HEVC

## Troubleshooting [#troubleshooting]

### CORS Issues [#cors-issues]

When cropping images from external domains, ensure proper CORS headers:

```tsx
<CropperImage
  src="https://example.com/image.jpg"
  crossOrigin="anonymous"
  alt="External image"
/>
```

### Performance with Large Media [#performance-with-large-media]

For large images or videos, consider:

1. Pre-processing media to reasonable sizes
2. Using `snapPixels` for crisp rendering
3. Limiting zoom range with `minZoom` and `maxZoom`
4. Reducing `keyboardStep` for smoother interactions

### Mobile Considerations [#mobile-considerations]

On mobile devices:

* Use appropriate viewport meta tags
* Consider touch target sizes for controls
* Test pinch-to-zoom interactions
* Ensure adequate spacing around interactive elements

## Credits [#credits]

* [Unsplash](https://unsplash.com/) - For the photos used in examples.
* [Blender Foundation](https://www.blender.org/) - For the video used in examples.


# Data Grid
URL: /docs/components/base/data-grid



<ComponentTabs name="data-grid-demo" />

## Installation [#installation]

<Steps>
  <Step>
    Install the main component and dependencies:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    Install the following optional components:

    [`getDataGridSelectColumn`](#getdatagridselectcolumn):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`getDataGridActionsColumn`](#getdatagridactionscolumn):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridSortMenu`](#datagridsortmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridFilterMenu`](#datagridfiltermenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridRowHeightMenu`](#datagridrowheightmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridViewMenu`](#datagridviewmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridKeyboardShortcuts`](#datagridkeyboardshortcuts):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridSkeleton`](#datagridskeleton):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`useDataGridUndoRedo`](#usedatagridundoredo):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>
</Steps>

## Usage [#usage]

### Basic Data Grid [#basic-data-grid]

```tsx
import { DataGrid } from "@/components/data-grid/data-grid";
import { DataGridKeyboardShortcuts } from "@/components/data-grid/data-grid-keyboard-shortcuts";
import { useDataGrid } from "@/hooks/use-data-grid";

export default function MyDataGrid() {
  const [data, setData] = React.useState(initialData);
  
  const columns = React.useMemo(() => [
    {
      id: "name",
      accessorKey: "name",
      header: "Name",
      meta: {
        cell: {
          variant: "short-text",
        },
      },
    },
    // ... other columns
  ], []);

  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
    onDataChange: setData,
    getRowId: (row) => row.id,
  });

  return (
    <>
      <DataGridKeyboardShortcuts />
      <DataGrid table={table} {...dataGridProps} />
    </>
  );
}
```

### With Toolbar Menus [#with-toolbar-menus]

Add sort, filter, row height, and view menus:

```tsx
import { DataGrid } from "@/components/data-grid/data-grid";
import { DataGridFilterMenu } from "@/components/data-grid/data-grid-filter-menu";
import { DataGridKeyboardShortcuts } from "@/components/data-grid/data-grid-keyboard-shortcuts";
import { DataGridRowHeightMenu } from "@/components/data-grid/data-grid-row-height-menu";
import { DataGridSortMenu } from "@/components/data-grid/data-grid-sort-menu";
import { DataGridViewMenu } from "@/components/data-grid/data-grid-view-menu";
import { useDataGrid } from "@/hooks/use-data-grid";

export default function DataGridToolbarDemo() {
  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
    onDataChange: setData,
  });

  return (
    <div className="flex flex-col gap-4">
      {/* Toolbar */}
      <div role="toolbar" aria-orientation="horizontal" className="flex items-center gap-2 self-end">
        <DataGridFilterMenu table={table} />
        <DataGridSortMenu table={table} />
        <DataGridRowHeightMenu table={table} />
        <DataGridViewMenu table={table} />
      </div>
      
      <DataGridKeyboardShortcuts />
      <DataGrid table={table} {...dataGridProps} />
    </div>
  );
}
```

### With Row Management [#with-row-management]

Add and delete rows with callbacks:

```tsx
const onRowAdd = React.useCallback(() => {
  const newRow = { id: generateId() };
  setData((prev) => [...prev, newRow]);
  
  return {
    rowId: newRow.id,
    columnId: "name", // Focus this column after creating the new row
  };
}, []);

const onRowsDelete = React.useCallback((rows, rowIds) => {
  // rows: array of row data objects
  // rowIds: array of row ids
  setData((prev) => prev.filter((row) => !rows.includes(row)));
}, []);

const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  onRowAdd,
  onRowsDelete,
  getRowId: (row) => row.id,
});
```

### With Search [#with-search]

Use the `enableSearch` prop to enable search functionality:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  enableSearch: true, // Enable search (Ctrl/Cmd+F)
});

return (
  <>
    <DataGridKeyboardShortcuts enableSearch />
    <DataGrid {...dataGridProps} table={table} />
  </>
);
```

### With Paste Support [#with-paste-support]

Use the `enablePaste` prop to enable pasting from clipboard:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  enablePaste: true, // Enable paste (Ctrl/Cmd+V)
  onRowsAdd: async (count) => {
    // Called when paste needs to add new rows
    // This is more performant than adding rows one by one with the `onRowAdd` prop
    const newRows = Array.from({ length: count }, () => ({ id: generateId() }));
    setData((prev) => [...prev, ...newRows]);
  },
});
```

### With Undo/Redo [#with-undoredo]

Use the `useDataGridUndoRedo` hook to add undo/redo support with keyboard shortcuts (Ctrl/Cmd+Z to undo, Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y to redo):

```tsx
import { useDataGrid } from "@/hooks/use-data-grid";
import {
  useDataGridUndoRedo,
  type UndoRedoCellUpdate,
} from "@/hooks/use-data-grid-undo-redo";

export default function MyDataGrid() {
  const [data, setData] = React.useState(initialData);

  const { trackCellsUpdate, trackRowsAdd, trackRowsDelete } =
    useDataGridUndoRedo({
      data,
      onDataChange: setData,
      getRowId: (row) => row.id,
    });

  const onDataChange = React.useCallback(
    (newData: Person[]) => {
      // Track cell updates for undo/redo
      const cellUpdates: Array<UndoRedoCellUpdate> = [];

      for (let rowIndex = 0; rowIndex < data.length; rowIndex++) {
        const oldRow = data[rowIndex];
        const newRow = newData[rowIndex];
        if (!oldRow || !newRow) continue;

        for (const key of Object.keys(oldRow)) {
          const oldValue = oldRow[key];
          const newValue = newRow[key];
          if (!Object.is(oldValue, newValue)) {
            cellUpdates.push({
              rowId: oldRow.id,
              columnId: key,
              previousValue: oldValue,
              newValue,
            });
          }
        }
      }

      if (cellUpdates.length > 0) {
        trackCellsUpdate(cellUpdates);
      }

      setData(newData);
    },
    [data, trackCellsUpdate],
  );

  const onRowAdd = React.useCallback(() => {
    const newRow = { id: generateId() };
    setData((prev) => [...prev, newRow]);
    trackRowsAdd([newRow]);
    return { rowId: newRow.id, columnId: "name" };
  }, [trackRowsAdd]);

  const onRowsDelete = React.useCallback(
    (rows) => {
      trackRowsDelete(rows);
      setData((prev) => prev.filter((row) => !rows.includes(row)));
    },
    [trackRowsDelete],
  );

  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
    onDataChange,
    onRowAdd,
    onRowsDelete,
    getRowId: (row) => row.id,
  });

  return (
    <>
      <DataGridKeyboardShortcuts enableUndoRedo />
      <DataGrid table={table} {...dataGridProps} />
    </>
  );
}
```

### Read-Only Mode [#read-only-mode]

Use the `readOnly` prop to make the grid read-only:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  readOnly: true, // Disable all editing
});
```

### RTL Support [#rtl-support]

Wrap the grid in a `DirectionProvider` and the language direction will be automatically detected. The `direction` component is included when you install the data grid — see the [shadcn Direction docs](https://ui.shadcn.com/docs/components/base/direction) for the underlying API.

```tsx
import { DirectionProvider } from "@/components/ui/direction";

return (
  <DirectionProvider dir="rtl">
    <DataGridImpl />
  </DirectionProvider>
)

function DataGridImpl() {
  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
  });

  return (
    <DataGrid table={table} {...dataGridProps} />
  )
}
```

### Auto Focus [#auto-focus]

Use the `autoFocus` prop to automatically focus any navigable cell on mount:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  autoFocus: true, // Focus first navigable cell
  // Or focus a specific cell:
  // autoFocus: { rowId: "row-1", columnId: "name" },
});
```

### Custom Height and Stretch Columns [#custom-height-and-stretch-columns]

Control the grid height and column stretching:

```tsx
<DataGrid 
  table={table} 
  {...dataGridProps} 
  height={800} // Custom height in pixels (default: 600)
  stretchColumns={true} // Stretch columns to fill available width
/>
```

### Loading States [#loading-states]

Use the `DataGridSkeleton` component for loading states:

```tsx
import { Suspense } from "react";
import {
  DataGridSkeleton,
  DataGridSkeletonGrid,
  DataGridSkeletonToolbar,
} from "@/components/data-grid/data-grid-skeleton";

export default function Page() {
  return (
    <Suspense
      fallback={
        <DataGridSkeleton className="container flex flex-col gap-4 py-4">
          <DataGridSkeletonToolbar actionCount={5} />
          <DataGridSkeletonGrid />
        </DataGridSkeleton>
      }
    >
      <DataGridDemo />
    </Suspense>
  );
}
```

## Cell Variants [#cell-variants]

The Data Grid supports various cell variants for different data formats:

### Short Text Cell [#short-text-cell]

Single-line text input with inline editing:

```tsx
{
  id: "name",
  accessorKey: "name",
  header: "Name",
  meta: {
    cell: {
      variant: "short-text",
    },
  },
}
```

### Long Text Cell [#long-text-cell]

Multi-line text displayed in a popover with auto-save:

```tsx
{
  id: "notes",
  accessorKey: "notes",
  header: "Notes",
  meta: {
    cell: {
      variant: "long-text",
    },
  },
}
```

### Number Cell [#number-cell]

Numeric input with optional constraints:

```tsx
{
  id: "price",
  accessorKey: "price",
  header: "Price",
  meta: {
    cell: {
      variant: "number",
      min: 0,
      max: 1000,
      step: 0.01,
    },
  },
}
```

### URL Cell [#url-cell]

URL input with validation and clickable links:

```tsx
{
  id: "website",
  accessorKey: "website",
  header: "Website",
  meta: {
    cell: {
      variant: "url",
    },
  },
}
```

### Checkbox Cell [#checkbox-cell]

Boolean checkbox for true/false values:

```tsx
{
  id: "isActive",
  accessorKey: "isActive",
  header: "Active",
  meta: {
    cell: {
      variant: "checkbox",
    },
  },
}
```

### Select Cell [#select-cell]

Single-select input with predefined options:

```tsx
{
  id: "category",
  accessorKey: "category",
  header: "Category",
  meta: {
    cell: {
      variant: "select",
      options: [
        { label: "Electronics", value: "electronics" },
        { label: "Clothing", value: "clothing" },
        { label: "Books", value: "books" },
      ],
    },
  },
}
```

### Multi-Select Cell [#multi-select-cell]

Multi-select input with predefined options and badge display:

```tsx
{
  id: "skills",
  accessorKey: "skills",
  header: "Skills",
  meta: {
    cell: {
      variant: "multi-select",
      options: [
        { label: "JavaScript", value: "javascript" },
        { label: "TypeScript", value: "typescript" },
        { label: "React", value: "react" },
      ],
    },
  },
}
```

### Date Cell [#date-cell]

Date picker with calendar popover:

```tsx
{
  id: "startDate",
  accessorKey: "startDate",
  header: "Start Date",
  meta: {
    cell: {
      variant: "date",
    },
  },
}
```

### File Cell [#file-cell]

File upload with support for multiple files and file management:

```tsx
{
  id: "attachments",
  accessorKey: "attachments",
  header: "Attachments",
  meta: {
    cell: {
      variant: "file",
      maxFileSize: 10 * 1024 * 1024, // 10MB
      maxFiles: 5,
      accept: "image/*,video/*,audio/*,.pdf,.doc,.docx",
      multiple: true,
    },
  },
}
```

To use file cells, provide upload and delete handlers:

```tsx
const onFilesUpload = React.useCallback(async ({ files, rowId, columnId }) => {
  // Upload files to your server/storage
  const formData = new FormData();
  files.forEach(file => formData.append('files', file));
  
  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData
  });
  
  const data = await response.json();
  
  // Return array of file metadata
  return data.files.map(f => ({
    id: f.fileId,
    name: f.fileName,
    size: f.fileSize,
    type: f.fileType,
    url: f.fileUrl
  }));
}, []);

const onFilesDelete = React.useCallback(async ({ fileIds, rowId, columnId }) => {
  // Delete files from your server/storage
  await fetch('/api/files', {
    method: 'DELETE',
    body: JSON.stringify({ fileIds })
  });
}, []);

const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onFilesUpload,
  onFilesDelete,
});
```

## Row Selection [#row-selection]

Add a selection column to enable row selection with shift-click support using the `getDataGridSelectColumn` helper:

```tsx
import { getDataGridSelectColumn } from "@/components/data-grid/data-grid-select-column";

const columns = [
  getDataGridSelectColumn<YourData>(),
  // ... other columns
];
```

You can customize the select column by passing options:

```tsx
getDataGridSelectColumn<YourData>({
  size: 50, // Custom width (default: 40)
  enableHiding: true, // Allow hiding via view menu (default: false)
  enableResizing: true, // Allow resizing (default: false)
})
```

The shift-click functionality is handled automatically by the `useDataGrid` hook when you include the select column.

## Row Actions [#row-actions]

Add a menu of actions to each row with `getDataGridActionsColumn`, and show bulk actions for the selection with the `actionBar` prop. The action bar renders while rows or a range of cells are selected.

```tsx
import { getDataGridActionsColumn } from "@/components/data-grid/data-grid-actions-column";
import { getDataGridSelectColumn } from "@/components/data-grid/data-grid-select-column";
import { DropdownMenuItem } from "@/components/ui/dropdown-menu";

const columns = React.useMemo(() => [
  getDataGridSelectColumn(),
  // ... other columns
  getDataGridActionsColumn({
    actions: ({ row }) => (
      <DropdownMenuItem onClick={() => onRowDelete(row.original)}>
        Delete
      </DropdownMenuItem>
    ),
  }),
], [onRowDelete]);

const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  initialState: {
    columnPinning: { start: ["select"], end: ["actions"] },
  },
});

return (
  <DataGrid
    {...dataGridProps}
    table={table}
    actionBar={<TasksActionBar table={table} />}
  />
);
```

## Cell Architecture [#cell-architecture]

The Data Grid uses a three-layer cell composition pattern:

1. **DataGridCell**: Routes to the appropriate cell variant based on the column's `meta.cell.variant` property
2. **Cell Variants**: Implement specific editing UIs for different data variants (text, number, select, etc.)
3. **DataGridCellWrapper**: Provides common functionality for all cells (focus, selection, keyboard interactions)

```tsx
// Cell composition flow
<DataGridCell {...cellProps} />
  ↓
<ShortTextCell {...props} />  // Based on variant
  ↓
<DataGridCellWrapper {...props}>
  {/* Cell-specific content */}
</DataGridCellWrapper>
```

Each cell variant receives the same props and wraps its content in `DataGridCellWrapper`, which provides:

* Focus management and visual focus ring
* Selection state and highlighting
* Search match highlighting
* Click, double-click, and keyboard event management
* Edit mode triggering (Enter, F2, Space, or typing)

### Creating Custom Cell Variants [#creating-custom-cell-variants]

You can create custom cell variants by implementing the `DataGridCellProps` interface and wrapping your content in `DataGridCellWrapper`:

```tsx
import { DataGridCellWrapper } from "@/components/data-grid/data-grid-cell-wrapper";
import type { DataGridCellProps } from "@/lib/data-grid-types";

export function CustomCell<TData>(props: DataGridCellProps<TData>) {
  const { cell, isEditing, readOnly } = props;
  const value = cell.getValue() as CustomCellValue;

  function onCommit(nextValue: CustomCellValue) {
    if (!readOnly) cell.setValue(nextValue);
    cell.table.stopEditing();
  }

  return (
    <DataGridCellWrapper {...props}>
      {/* Your custom cell content */}
    </DataGridCellWrapper>
  );
}
```

Cells read and write data through the cell, with `cell.getValue()` and `cell.setValue()`, and control edit mode with `cell.startEditing()` and `cell.table.stopEditing()`.

## Column Configuration [#column-configuration]

### Enabling Filtering and Sorting [#enabling-filtering-and-sorting]

To enable filtering and sorting on columns, use the `filterFn` from the data grid library:

```tsx
import { getFilterFn } from "@/lib/data-grid-filters";

const columns = React.useMemo(() => {
  const filterFn = getFilterFn<YourData>();
  
  return [
    {
      id: "name",
      accessorKey: "name",
      header: "Name",
      filterFn, // Enable filtering
      // Sorting is enabled by default
      meta: {
        label: "Name", // Label shown in filter/sort menus
        cell: {
          variant: "short-text",
        },
      },
    },
    // ... other columns
  ];
}, []);
```

### Column Pinning [#column-pinning]

Pin columns to the left or right:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  initialState: {
    columnPinning: {
      start: ["select", "name"], // Pin to the start side
      end: ["actions"], // Pin to the end side
    },
  },
});
```

You can also pin/unpin columns dynamically via the column header dropdown menu.

### Column Resizing [#column-resizing]

Column resizing is enabled by default. Users can:

* Drag the column resize handle
* Double-click the resize handle to auto-fit the column width

Set minimum column size using `minSize`:

```tsx
{
  id: "name",
  accessorKey: "name",
  header: "Name",
  minSize: 180, // Minimum width in pixels
  meta: {
    cell: {
      variant: "short-text",
    },
  },
}
```

## Context Menu Actions [#context-menu-actions]

Right-click on cells to access context menu options:

* **Copy** (Ctrl/Cmd+C): Copy selected cells to clipboard
* **Cut** (Ctrl/Cmd+X): Cut selected cells (shows visual indicator)
* **Clear** (Delete/Backspace): Clear content from selected cells
* **Delete rows** (Ctrl/Cmd+Backspace): Remove selected rows (only available when `onRowsDelete` is provided)

## API Reference [#api-reference]

### useDataGrid [#usedatagrid]

Hook for initializing the data grid with state management and editing capabilities.

<AutoTypeTable path="./types/base/data-grid.ts" name="UseDataGridProps" />

### useDataGridUndoRedo [#usedatagridundoredo]

Hook for adding undo/redo support to the data grid with keyboard shortcuts and history management.

<AutoTypeTable path="./types/base/data-grid.ts" name="UseDataGridUndoRedoProps" />

Returns:

<AutoTypeTable path="./types/base/data-grid.ts" name="UseDataGridUndoRedoReturn" />

### DataGrid [#datagrid]

Main data grid component with virtualization and editing capabilities.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridProps" />

### getDataGridSelectColumn [#getdatagridselectcolumn]

A utility function that returns a reusable select column definition for the data grid with checkbox selection and shift-click support.

<AutoTypeTable path="./types/base/data-grid.ts" name="GetDataGridSelectColumnProps" />

### getDataGridActionsColumn [#getdatagridactionscolumn]

A utility function that returns an actions column with a dropdown menu for each row.

<AutoTypeTable path="./types/base/data-grid.ts" name="GetDataGridActionsColumnProps" />

### DataGridColumnHeader [#datagridcolumnheader]

Column header with sorting controls and visual indicators for sort direction.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridColumnHeaderProps" />

### DataGridCell [#datagridcell]

Routes to the appropriate cell variant based on the column's `meta.cell.variant` property.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridCellProps" />

### DataGridCellWrapper [#datagridcellwrapper]

Base wrapper providing common functionality for all cell variants including focus management, selection state, search highlighting, and keyboard interactions.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridCellWrapperProps" />

### DataGridCellVariants [#datagridcellvariants]

Individual cell variants for different data variants. Each variant implements the `DataGridCellProps` interface and wraps its content in `DataGridCellWrapper`.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridCellProps" />

Available cell variants:

* **ShortTextCell**: Single-line text input with inline contentEditable
* **LongTextCell**: Multi-line textarea displayed in a popover dialog with auto-save
* **NumberCell**: Numeric input with optional min, max, and step constraints
* **UrlCell**: URL input with validation and clickable links
* **SelectCell**: Single-select dropdown with predefined options
* **MultiSelectCell**: Multi-select input with badge display and command palette
* **CheckboxCell**: Boolean checkbox for true/false values
* **DateCell**: Date picker with calendar popover
* **FileCell**: File upload with support for multiple files and file management

### DataGridRow [#datagridrow]

Individual row component with virtualization support for large datasets.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridRowProps" />

### DataGridSearch [#datagridsearch]

Search menu with keyboard shortcuts for finding and navigating between matching cells in the grid.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridSearchProps" />

### DataGridFilterMenu [#datagridfiltermenu]

Filter menu with drag-and-drop reordering and advanced filtering operators for text, number, date, select, and boolean fields.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridFilterMenuProps" />

### DataGridSortMenu [#datagridsortmenu]

Sort menu with drag-and-drop reordering for multi-column sorting with ascending/descending controls.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridSortMenuProps" />

### DataGridRowHeightMenu [#datagridrowheightmenu]

Row height menu for adjusting row sizes between short, medium, tall, and extra-tall options.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridRowHeightMenuProps" />

### DataGridViewMenu [#datagridviewmenu]

View menu for controlling column visibility with search functionality.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridViewMenuProps" />

### DataGridContextMenu [#datagridcontextmenu]

Right-click context menu for quick access to common cell and row actions like copy, cut, clear, and delete.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridContextMenuProps" />

### DataGridPasteDialog [#datagridpastedialog]

Dialog for handling paste operations that require adding new rows to the grid.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridPasteDialogProps" />

### DataGridKeyboardShortcuts [#datagridkeyboardshortcuts]

Searchable reference dialog for all available keyboard shortcuts for navigating and interacting with the data grid.

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridKeyboardShortcutsProps" />

### DataGridSkeleton [#datagridskeleton]

A composable skeleton component for the data grid with toolbar and grid parts for loading states.

```tsx
import {
  DataGridSkeleton,
  DataGridSkeletonGrid,
  DataGridSkeletonToolbar,
} from "@/components/data-grid/data-grid-skeleton";

return (
  <DataGridSkeleton>
    <DataGridSkeletonToolbar />
    <DataGridSkeletonGrid />
  </DataGridSkeleton>
);
```

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridSkeletonProps" />

#### DataGridSkeletonToolbar [#datagridskeletontoolbar]

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridSkeletonToolbarProps" />

#### DataGridSkeletonGrid [#datagridskeletongrid]

<AutoTypeTable path="./types/base/data-grid.ts" name="DataGridSkeletonGridProps" />

## Accessibility [#accessibility]

The Data Grid follows WAI-ARIA guidelines for grid widgets:

* Full keyboard navigation support
* Proper ARIA labels, roles, and properties
* Focus management with visible focus indicators
* Keyboard shortcuts for all actions
* Screen reader friendly cell updates

## Keyboard Interactions [#keyboard-interactions]

### Navigation [#navigation]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;↑&#x22;, &#x22;↓&#x22;, &#x22;←&#x22;, &#x22;→&#x22;],
    description: &#x22;Navigate between cells&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Move to next cell&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Move to previous cell&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Move to first column&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Move to last column&#x22;,
  },
  {
    keys: [&#x22;Ctrl + ↑&#x22;, &#x22;Cmd + ↑&#x22;],
    description: &#x22;Move to first row (same column)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + ↓&#x22;, &#x22;Cmd + ↓&#x22;],
    description: &#x22;Move to last row (same column)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + ←&#x22;, &#x22;Cmd + ←&#x22;],
    description: &#x22;Move to first column (same row)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + →&#x22;, &#x22;Cmd + →&#x22;],
    description: &#x22;Move to last column (same row)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Home&#x22;, &#x22;Cmd + Home&#x22;],
    description: &#x22;Move to first cell&#x22;,
  },
  {
    keys: [&#x22;Ctrl + End&#x22;, &#x22;Cmd + End&#x22;],
    description: &#x22;Move to last cell&#x22;,
  },
  {
    keys: [&#x22;PgUp&#x22;],
    description: &#x22;Move up one page&#x22;,
  },
  {
    keys: [&#x22;PgDn&#x22;],
    description: &#x22;Move down one page&#x22;,
  },
  {
    keys: [&#x22;Alt + ↑&#x22;],
    description: &#x22;Scroll up one page&#x22;,
  },
  {
    keys: [&#x22;Alt + ↓&#x22;],
    description: &#x22;Scroll down one page&#x22;,
  },
  {
    keys: [&#x22;Alt + PgUp&#x22;],
    description: &#x22;Scroll left one page of columns&#x22;,
  },
  {
    keys: [&#x22;Alt + PgDn&#x22;],
    description: &#x22;Scroll right one page of columns&#x22;,
  },
]"
/>

### Selection [#selection]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Shift + ↑&#x22;, &#x22;Shift + ↓&#x22;, &#x22;Shift + ←&#x22;, &#x22;Shift + →&#x22;],
    description: &#x22;Extend selection&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + ↑&#x22;, &#x22;Cmd + Shift + ↑&#x22;],
    description: &#x22;Select to top of table&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + ↓&#x22;, &#x22;Cmd + Shift + ↓&#x22;],
    description: &#x22;Select to bottom of table&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + ←&#x22;, &#x22;Cmd + Shift + ←&#x22;],
    description: &#x22;Select to first column&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + →&#x22;, &#x22;Cmd + Shift + →&#x22;],
    description: &#x22;Select to last column&#x22;,
  },
  {
    keys: [&#x22;Ctrl + A&#x22;, &#x22;Cmd + A&#x22;],
    description: &#x22;Select all cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Click&#x22;, &#x22;Cmd + Click&#x22;],
    description: &#x22;Toggle cell selection&#x22;,
  },
  {
    keys: [&#x22;Shift + Click&#x22;],
    description: &#x22;Select range&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Clear selection or exit edit mode&#x22;,
  },
]"
/>

### Editing [#editing]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Start editing cell&#x22;,
  },
  {
    keys: [&#x22;F2&#x22;],
    description: &#x22;Start editing cell&#x22;,
  },
  {
    keys: [&#x22;Double Click&#x22;],
    description: &#x22;Start editing cell&#x22;,
  },
  {
    keys: [&#x22;Shift + Enter&#x22;],
    description: &#x22;Insert row below&#x22;,
  },
  {
    keys: [&#x22;Ctrl + C&#x22;, &#x22;Cmd + C&#x22;],
    description: &#x22;Copy selected cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + X&#x22;, &#x22;Cmd + X&#x22;],
    description: &#x22;Cut selected cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + V&#x22;, &#x22;Cmd + V&#x22;],
    description: &#x22;Paste cells&#x22;,
  },
  {
    keys: [&#x22;Delete&#x22;],
    description: &#x22;Clear selected cells&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;Clear selected cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Backspace&#x22;, &#x22;Cmd + Backspace&#x22;],
    description: &#x22;Delete selected rows&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Delete&#x22;, &#x22;Cmd + Delete&#x22;],
    description: &#x22;Delete selected rows&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Z&#x22;, &#x22;Cmd + Z&#x22;],
    description: &#x22;Undo last action&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + Z&#x22;, &#x22;Cmd + Shift + Z&#x22;],
    description: &#x22;Redo last action&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Y&#x22;, &#x22;Cmd + Y&#x22;],
    description: &#x22;Redo last action&#x22;,
  },
]"
/>

### Search & Shortcuts [#search--shortcuts]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Ctrl + F&#x22;, &#x22;Cmd + F&#x22;],
    description: &#x22;Open search&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Next search match (when search is open)&#x22;,
  },
  {
    keys: [&#x22;Shift + Enter&#x22;],
    description: &#x22;Previous search match (when search is open)&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Close search (when search is open)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + F&#x22;, &#x22;Cmd + Shift + F&#x22;],
    description: &#x22;Toggle filter menu&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + S&#x22;, &#x22;Cmd + Shift + S&#x22;],
    description: &#x22;Toggle sort menu&#x22;,
  },
  {
    keys: [&#x22;Ctrl + /&#x22;, &#x22;Cmd + /&#x22;],
    description: &#x22;Show keyboard shortcuts&#x22;,
  },
]"
/>

## Features [#features]

The Data Grid component provides a comprehensive spreadsheet-like experience with:

### Core Features [#core-features]

* **High Performance**: Virtualized rows and columns for handling large datasets (10,000+ rows)
* **Cell Editing**: In-place editing with 9 different cell variants
* **Cell Selection**: Single and multi-cell selection with keyboard and mouse
* **Keyboard Navigation**: Full keyboard support with Excel-like shortcuts
* **Copy/Cut/Paste**: Full clipboard support including paste from Excel/Google Sheets
* **Undo/Redo**: Full history support for cell updates, row additions, and deletions (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z)
* **Context Menu**: Right-click actions for cells and rows
* **Search**: Find and navigate to matching cells (Ctrl/Cmd+F)
* **Filtering**: Advanced filtering with multiple operators and drag-and-drop reordering
* **Sorting**: Multi-column sorting with drag-and-drop reordering
* **Row Management**: Add and delete rows with callbacks
* **Column Features**: Resizing, pinning (left/right), hiding, and reordering

### Cell Variants [#cell-variants-1]

* **Text Cells**: Short-text and long-text with auto-save
* **Number Cells**: With min/max/step constraints
* **URL Cells**: With validation and clickable links
* **Date Cells**: Calendar picker with keyboard navigation
* **Select Cells**: Single and multi-select with search
* **Checkbox Cells**: Boolean values
* **File Cells**: Upload and manage multiple files per cell

### Advanced Features [#advanced-features]

* **Smart Paste**: Automatically expands grid when pasting more data than fits
* **Auto-Fill**: Type to start editing, like in Excel
* **Row Heights**: Adjustable row heights (short, medium, tall, extra-tall)
* **RTL Support**: Full right-to-left language support
* **Read-Only Mode**: Lock the grid to prevent editing
* **Auto-Focus**: Focus specific cell on mount
* **Accessibility**: Full ARIA support and keyboard navigation

## Credits [#credits]

* [TanStack Table](https://tanstack.com/table) - For the table state management.
* [TanStack Virtual](https://tanstack.com/virtual) - For the virtualization.
* [shadcn/ui](https://ui.shadcn.com) - For the UI components.
* [Airtable](https://www.airtable.com) and [Glide Data Grid](https://grid.glideapps.com/) - For accessibility and best practices.


# Data Table
URL: /docs/components/base/data-table



<ComponentTabs name="data-table-demo" className="p-4" />

## Installation [#installation]

<Steps>
  <Step>
    Install the main component and dependencies:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Filter and sort menu installs bundle a `sortable` component. Primitives come from [`Base UI`](https://base-ui.com).
  </Step>

  <Step>
    Wrap your application with the [`NuqsAdapter`](https://nuqs.47ng.com/docs/adapters) for query state management:

    ```tsx
    import { NuqsAdapter } from "nuqs/adapters/next/app";

    <NuqsAdapter>
      <App />
    </NuqsAdapter>
    ```
  </Step>

  <Step>
    Install the following optional components:

    [`DataTableSortMenu`](#datatablesortmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataTableFilterMenu`](#datatablefiltermenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataTableCommandFilterMenu`](#datatablecommandfiltermenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`getDataTableSelectColumn`](#row-selection):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`getDataTableActionsColumn`](#row-actions):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>
</Steps>

## Layout [#layout]

Import the components and compose them together:

```tsx
import { DataTable } from "@/components/data-table/data-table";
import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";
import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
import { useDataTable } from "@/hooks/use-data-table";

const { table } = useDataTable({
  data,
  columns,
  pageCount,
});

return (
  <DataTable table={table}>
    <DataTableToolbar table={table}>
      <DataTableSortMenu table={table} />
    </DataTableToolbar>
  </DataTable>
);
```

For the advanced toolbar with a filter menu, swap the toolbar:

```tsx
import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu";

return (
  <DataTable table={table}>
    <DataTableAdvancedToolbar table={table}>
      <DataTableFilterMenu table={table} />
      <DataTableSortMenu table={table} />
    </DataTableAdvancedToolbar>
  </DataTable>
);
```

## Walkthrough [#walkthrough]

<Steps>
  <Step>
    Define columns with appropriate metadata:

    ```tsx
    import { Text, CalendarIcon, DollarSign } from "lucide-react";
    import { DataTableColumnHeader } from "@/components/data-table/data-table-column-header";

    const columns = React.useMemo(() => [
      {
        // Provide an unique id for the column
        // This id will be used as query key for the column filter
        id: "title", // [!code highlight]
        accessorKey: "title",
        header: ({ column }) => (
          <DataTableColumnHeader column={column} label="Title" />
        ),
        cell: ({ row }) => <div>{row.getValue("title")}</div>,
        // Define the column meta options for sorting, filtering, and view options
        meta: { // [!code highlight]
          label: "Title", // [!code highlight]
          placeholder: "Search titles...", // [!code highlight]
          variant: "text", // [!code highlight]
          icon: Text, // [!code highlight]
        }, // [!code highlight] 
        // By default, the column will not be filtered. Set to `true` to enable filtering.
        enableColumnFilter: true, // [!code highlight]
      },
    ], []);
    ```
  </Step>

  <Step>
    Initialize the table state using the `useDataTable` hook:

    ```tsx
    import { useDataTable } from "@/hooks/use-data-table";

    function DataTableDemo() {
      const { table } = useDataTable({
        data,
        columns,
        // Pass the total number of pages for server-side data,
        // or set `mode: "client"` to sort, filter, and paginate in the browser
        pageCount, // [!code highlight]
        initialState: {
          sorting: [{ id: "createdAt", desc: true }],
          pagination: { pageSize: 10 },
        },
        // Unique identifier for rows, can be used for unique row selection
        getRowId: (row) => row.id, // [!code highlight]
      });

      return (
        // ... render table
      );
    }
    ```
  </Step>

  <Step>
    Pass the table instance to the `DataTable`, and `DataTableToolbar` components:

    ```tsx
    import { DataTable } from "@/components/data-table/data-table";
    import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
    import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";

    function DataTableDemo() {
      return (
        <DataTable table={table}>
          <DataTableToolbar table={table}>
            <DataTableSortMenu table={table} />
          </DataTableToolbar>
        </DataTable>
      );
    }
    ```
  </Step>

  <Step>
    For advanced filtering, use the `DataTableAdvancedToolbar` component:

    ```tsx
    import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
    import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu";
    import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";

    function DataTableDemo() {
      return (
        <DataTable table={table}>
          <DataTableAdvancedToolbar table={table}>
            <DataTableFilterMenu table={table} />
            <DataTableSortMenu table={table} />
          </DataTableAdvancedToolbar>
        </DataTable>
      );
    }
    ```
  </Step>

  <Step>
    Alternatively, swap out `DataTableFilterMenu` with `DataTableCommandFilterMenu` for a command palette-style interface:

    ```tsx
    import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
    import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu"; // [!code --]
    import { DataTableCommandFilterMenu } from "@/components/data-table/data-table-command-filter-menu"; // [!code ++]
    import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";

    function DataTableDemo() {
      return (
        <DataTable table={table}>
          <DataTableAdvancedToolbar table={table}>
            {/* [!code --] */}
            <DataTableFilterMenu table={table} />
            {/* [!code ++] */}
            <DataTableCommandFilterMenu table={table} />
            <DataTableSortMenu table={table} />
          </DataTableAdvancedToolbar>
        </DataTable>
      );
    }
    ```
  </Step>

  <Step>
    Render an action bar on row selection:

    ```tsx
    import { ActionBar } from "@/components/ui/action-bar";

    function TableActionBar({ table }: { table: Table<Data> }) {
      const rows = table.getFilteredSelectedRowModel().rows;

      const onOpenChange = React.useCallback((open: boolean) => {
        if (!open) {
          table.toggleAllRowsSelected(false);
        }
      },
      [table],
    );
      
      return (
        <ActionBar open={rows.length > 0} onOpenChange={onOpenChange}>
          {/* Add your custom actions here */}
        </ActionBar>
      );
    }

    function DataTableDemo() {
      return (
        <DataTable 
          table={table}
          actionBar={<TableActionBar table={table} />}
        >
          <DataTableToolbar table={table} />
        </DataTable>
      );
    }
    ```
  </Step>
</Steps>

## Row Selection [#row-selection]

Use `getDataTableSelectColumn` to add a checkbox column for selecting rows:

```tsx
import { getDataTableSelectColumn } from "@/components/data-table/data-table-select-column";

const columns = React.useMemo<ColumnDef<DataTableFeatures, Project>[]>(
  () => [
    getDataTableSelectColumn(),
    // ...other columns
  ],
  [],
);
```

Cells are memoized and only re-render when the state they subscribe to changes. If you render your own selection-dependent cell, read the selection inside `Subscribe` instead of calling `row.getIsSelected()` directly:

```tsx
import { Subscribe } from "@tanstack/react-table";

cell: ({ row }) => (
  <Subscribe
    source={row.table.atoms.rowSelection}
    selector={(selection) => selection[row.id] === true}
  >
    {(isSelected) => (
      <Checkbox
        checked={isSelected}
        onCheckedChange={(value) => row.toggleSelected(!!value)}
      />
    )}
  </Subscribe>
),
```

## Row Actions [#row-actions]

Use `getDataTableActionsColumn` to add a menu of actions to each row:

```tsx
import { getDataTableActionsColumn } from "@/components/data-table/data-table-actions-column";
import { DropdownMenuItem } from "@/components/ui/dropdown-menu";

const columns = React.useMemo<ColumnDef<DataTableFeatures, Project>[]>(
  () => [
    // ...other columns
    getDataTableActionsColumn({
      actions: ({ row }) => (
        <DropdownMenuItem onClick={() => onRowDelete(row.original)}>
          Delete
        </DropdownMenuItem>
      ),
    }),
  ],
  [onRowDelete],
);
```

Pin it to the end with `initialState.columnPinning.end`, like `{ start: ["select"], end: ["actions"] }`.

## Client and Server Mode [#client-and-server-mode]

`useDataTable` runs in one of two modes. Both keep pagination, sorting, and filters in the URL.

<PropsTable
  variant="title"
  data="[
  {
    title: &#x22;server&#x22;,
    description: &#x22;Default. Pass the current page of `data` and the total `pageCount` (required). Read the URL state on the server and query your database.&#x22;,
  },
  {
    title: &#x22;client&#x22;,
    description: &#x22;Pass all rows as `data` and omit `pageCount`. The hook sorts, filters, and paginates them in the browser and derives the page count.&#x22;,
  },
]"
/>

`pageCount` is required in server mode and not allowed in client mode. TypeScript reports an error if you pass it in client mode or leave it out in server mode.

### Client Mode [#client-mode]

Use client mode when the full dataset fits in the browser:

```tsx
const { table } = useDataTable({
  mode: "client",
  data,
  columns,
  getRowId: (row) => row.id,
});
```

### Server Mode [#server-mode]

Use server mode for large datasets. Describe the filterable and sortable columns once, and share that config between the server and the column definitions.

<Steps>
  <Step>
    Define the column configs and search params:

    ```ts title="lib/validations.ts"
    import { createSearchParamsCache } from "nuqs/server";

    import type { DataTableColumnConfig } from "@/lib/data-table-types";
    import { getDataTableSearchParams } from "@/lib/data-table-parsers";

    export const tasksColumnConfigs = {
      // Sortable, not filterable
      code: { isSortable: false },
      title: { variant: "text" },
      status: { variant: "multiSelect" },
      estimatedHours: { variant: "range" },
      createdAt: { variant: "dateRange" },
    } as const satisfies Record<string, DataTableColumnConfig>;

    export const searchParamsCache = createSearchParamsCache(
      getDataTableSearchParams({
        columnConfigs: tasksColumnConfigs,
        defaultSorting: [{ id: "createdAt", desc: true }],
      }),
    );
    ```
  </Step>

  <Step>
    Parse the search params on the server and turn them into a query:

    ```tsx title="app/page.tsx"
    import { getDataTableQuery } from "@/lib/data-table-parsers";

    export default async function Page(props: {
      searchParams: Promise<Record<string, string | string[] | undefined>>;
    }) {
      const search = searchParamsCache.parse(await props.searchParams);
      // { page, perPage, sorting, filters, joinOperator }
      const query = getDataTableQuery(search, tasksColumnConfigs);
      const { data, pageCount } = await getTasks(query);

      return <TasksTable data={data} pageCount={pageCount} />;
    }
    ```

    Type the query function's input with `DataTableColumnConfigsQuery<typeof tasksColumnConfigs>`. Each filter has an `id`, `variant`, `operator`, and `value` to map onto your database query.
  </Step>

  <Step>
    Spread `getColumnOptions` into each column so filtering and sorting match the config:

    ```tsx
    import { getColumnOptions } from "@/lib/data-table-parsers";

    {
      id: "title",
      accessorKey: "title",
      meta: { label: "Title", variant: "text" },
      ...getColumnOptions(tasksColumnConfigs.title), // [!code highlight]
    }
    ```
  </Step>

  <Step>
    Pass the server data and `pageCount` to `useDataTable`. Pass `startTransition` from `React.useTransition()` to show loading states while the server re-renders:

    ```tsx
    const [isPending, startTransition] = React.useTransition();

    const { table } = useDataTable({
      data,
      columns,
      pageCount,
      startTransition,
    });
    ```
  </Step>
</Steps>

### URL Format [#url-format]

Each filterable column has its own search param, keyed by column id. The value is the operator followed by the filter value. When a filter uses the column's default operator, the operator is left out.

```txt
?title=report                     # text, default operator (contains)
?title=eq.Weekly%20report         # text, "is"
?status=todo,done                 # multi-select, default operator (has any of)
?estimatedHours=2,8               # range, default operator (between)
?estimatedHours=gt.4              # range, "is greater than"
?createdAt=is.empty               # no value
?sort=createdAt.desc,title.asc
?joinOperator=or
```

## API Reference [#api-reference]

### Column Definitions [#column-definitions]

The column definitions are used to define the columns of the data table.

```tsx
const columns = React.useMemo<ColumnDef<Project>[]>(() => [
  {
    // Required: Unique identifier for the column
    id: "title", // [!code highlight]
    // Required: Key to access the data, `accessorFn` can also be used
    accessorKey: "title", // [!code highlight]
    // Optional: Custom header component
    header: ({ column }) => (
      <DataTableColumnHeader column={column} label="Title" />
    ),
    // Optional: Custom cell component
    cell: ({ row }) => <div>{row.getValue("title")}</div>,
    // Optional: Meta options for filtering, sorting, and view options
    meta: {
      label: "Title",
      placeholder: "Search titles...",
      variant: "text",
      icon: Text,
    },
    // By default, the column will not be filtered. Set to `true` to enable filtering.
    enableColumnFilter: true, // [!code highlight]
  },
  {
    id: "status",
    // Access nested data using `accessorFn`
    accessorFn: (row) => row.lineItem.status,
    header: "Status",
    meta: {
      label: "Status",
      variant: "select",
      options: [
        { label: "Active", value: "active" },
        { label: "Inactive", value: "inactive" },
      ],
    },
    enableColumnFilter: true,
  },
], []);
```

#### Properties [#properties]

Core configuration options for defining columns.

<PropsTable
  data="[
  {
    title: &#x22;id&#x22;,
    description: &#x22;Required: Unique identifier for the column&#x22;,
  },
  {
    title: &#x22;accessorKey&#x22;,
    description: &#x22;Required: Key to access the data from the row&#x22;,
  },
  {
    title: &#x22;accessorFn&#x22;,
    description: &#x22;Optional: Custom accessor function to access data&#x22;,
  },
  {
    title: &#x22;header&#x22;,
    description: &#x22;Optional: Custom header component with column props&#x22;,
  },
  {
    title: &#x22;cell&#x22;,
    description: &#x22;Optional: Custom cell component with row props&#x22;,
  },
  {
    title: &#x22;meta&#x22;,
    description: &#x22;Optional: Meta options for accessing column metadata&#x22;,
  },
  {
    title: &#x22;enableColumnFilter&#x22;,
    description: &#x22;By default, the column will not be filtered. Set to `true` to enable filtering&#x22;,
  },
  {
    title: &#x22;enableSorting&#x22;,
    description: &#x22;Enable sorting for this column&#x22;,
  },
  {
    title: &#x22;enableHiding&#x22;,
    description: &#x22;Enable column visibility toggle&#x22;,
  },
]"
/>

#### Column Meta [#column-meta]

Column meta options for filtering, sorting, and view options.

<PropsTable
  data="[
  {
    title: &#x22;label&#x22;,
    description: &#x22;The display name for the column&#x22;,
  },
  {
    title: &#x22;placeholder&#x22;,
    description: &#x22;The placeholder text for filter inputs&#x22;,
  },
  {
    title: &#x22;variant&#x22;,
    description: &#x22;The type of filter to use (`text`, `number`, `select`, etc.)&#x22;,
  },
  {
    title: &#x22;options&#x22;,
    description: &#x22;For select/multi-select filters, an array of options with `label`, `value`, and optional `count` and `icon`&#x22;,
  },
  {
    title: &#x22;range&#x22;,
    description: &#x22;For range filters, a tuple of `[min, max]` values&#x22;,
  },
  {
    title: &#x22;unit&#x22;,
    description: &#x22;For numeric filters, the unit to display (e.g., 'hr', '$')&#x22;,
  },
  {
    title: &#x22;icon&#x22;,
    description: &#x22;The react component to use as an icon for the column&#x22;,
  },
]"
/>

#### Filter Variants [#filter-variants]

Available filter variants for [column meta](#column-meta).

<PropsTable
  variant="title"
  data="[
  {
    title: &#x22;text&#x22;,
    description: &#x22;Text search with contains, equals, etc.&#x22;,
  },
  {
    title: &#x22;number&#x22;,
    description: &#x22;Numeric filters with equals, greater than, less than, etc.&#x22;,
  },
  {
    title: &#x22;range&#x22;,
    description: &#x22;Range filters with minimum and maximum values&#x22;,
  },
  {
    title: &#x22;date&#x22;,
    description: &#x22;Date filters with equals, before, after, etc.&#x22;,
  },
  {
    title: &#x22;dateRange&#x22;,
    description: &#x22;Date range filters with start and end dates&#x22;,
  },
  {
    title: &#x22;boolean&#x22;,
    description: &#x22;Boolean filters with true/false values&#x22;,
  },
  {
    title: &#x22;select&#x22;,
    description: &#x22;Single-select filters with predefined options&#x22;,
  },
  {
    title: &#x22;multiSelect&#x22;,
    description: &#x22;Multi-select filters with predefined options&#x22;,
  },
]"
/>

Reference the [TanStack Table Column Definitions Guide](https://tanstack.com/table/latest/docs/guide/column-defs#column-definitions-guide) for detailed column definition guide.

### useDataTable [#usedatatable]

A hook for initializing the data table with state management.

<AutoTypeTable path="./types/base/data-table.ts" name="UseDataTableProps" />

### DataTable [#datatable]

The main data table component.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableProps" />

### getDataTableActionsColumn [#getdatatableactionscolumn]

A utility function that returns an actions column with a dropdown menu for each row.

<AutoTypeTable path="./types/base/data-table.ts" name="GetDataTableActionsColumnProps" />

### DataTableColumnHeader [#datatablecolumnheader]

Custom header component for columns with sorting.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableColumnHeaderProps" />

### DataTableToolbar [#datatabletoolbar]

Standard toolbar with filtering and view options.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableToolbarProps" />

### DataTableAdvancedToolbar [#datatableadvancedtoolbar]

Advanced toolbar with more comprehensive filtering capabilities.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableAdvancedToolbarProps" />

### DataTableViewOptions [#datatableviewoptions]

Controls column visibility and display preferences in the data table.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableViewOptionsProps" />

### DataTableSortMenu [#datatablesortmenu]

List of applied sorting with ability to add, remove, and modify sorting.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableSortMenuProps" />

### DataTableFilterMenu [#datatablefiltermenu]

List of applied filters with ability to add, remove, and modify filters.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableFilterMenuProps" />

### DataTableCommandFilterMenu [#datatablecommandfiltermenu]

Command palette-style filter menu with ability to add, remove, and modify filters.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTableCommandFilterMenuProps" />

### DataTablePagination [#datatablepagination]

Pagination controls for the data table.

<AutoTypeTable path="./types/base/data-table.ts" name="DataTablePaginationProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Ctrl + Shift + F&#x22;, &#x22;Cmd + Shift + F&#x22;],
    description: &#x22;Toggles the filter menu.&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + S&#x22;, &#x22;Cmd + Shift + S&#x22;],
    description: &#x22;Toggles the sort menu.&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;, &#x22;Delete&#x22;],
    description: &#x22;Removes the focused filter/sort item. Removes the last applied filter/sort when menu trigger is focused.&#x22;,
  },
]"
/>

## Features [#features]

* **Advanced Filtering** - Multiple filter types (text, number, date, select, multi-select) with customizable operators
* **URL State Management** - Sync table state with URL search params using [nuqs](https://nuqs.47ng.com)
* **Sorting** - Multi-column sorting with persistent state
* **Pagination** - Server-side or client-side pagination with customizable page sizes
* **Column Visibility** - Toggle column visibility with view options menu
* **Row Selection** - Single or multi-row selection with action bar
* **Column Pinning** - Pin columns to left or right for better UX
* **Keyboard Navigation** - Full keyboard support with shortcuts for filter and sort menus
* **Responsive** - Mobile-first design with overflow handling
* **Customizable** - Flexible API for custom filters, columns, and actions

## Credits [#credits]

* [shadcn/ui](https://github.com/shadcn-ui/ui/tree/main/apps/www/app/\(app\)/examples/tasks) - For the initial implementation of the data table.


# Editable
URL: /docs/components/base/editable



<ComponentTabs name="editable-demo" className="items-start justify-start [&>div]:pt-20" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="editable" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Editable,
  EditableLabel,
  EditableArea,
  EditablePreview,
  EditableInput,
  EditableTrigger,
  EditableToolbar,
  EditableSubmit,
  EditableCancel,
} from "@/components/ui/editable";

return (
  <Editable>
    <EditableLabel />
    <EditableArea>
      <EditablePreview />
      <EditableInput />
      <EditableTrigger />
    </EditableArea>
    <EditableTrigger />
    <EditableToolbar>
      <EditableSubmit />
      <EditableCancel />
    </EditableToolbar>
  </Editable>
)
```

## Examples [#examples]

### With Double Click [#with-double-click]

Trigger edit mode with double click instead of single click.

<ComponentTabs name="editable-double-click-demo" className="items-start justify-start [&>div]:pt-20" />

### With Autosize [#with-autosize]

Input that automatically resizes based on content.

<ComponentTabs name="editable-autosize-demo" className="items-start justify-start [&>div]:pt-20" />

### Todo List [#todo-list]

<ComponentTabs name="editable-todo-list-demo" />

### With Form [#with-form]

Control the editable component in a form.

<ComponentTabs name="editable-form-demo" className="items-start justify-start [&>div]:pt-20" />

## API Reference [#api-reference]

### Editable [#editable]

The main container component for editable functionality.

<AutoTypeTable path="./types/base/editable.ts" name="EditableProps" />

### EditableLabel [#editablelabel]

The label component for the editable field.

<AutoTypeTable path="./types/base/editable.ts" name="EditableLabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the editable field is invalid&#x22;,
  },
  {
    title: &#x22;[data-required]&#x22;,
    value: &#x22;Present when the editable field is required&#x22;,
  },
]"
/>

### EditableArea [#editablearea]

Container for the preview and input components.

<AutoTypeTable path="./types/base/editable.ts" name="EditableAreaProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-editing]&#x22;,
    value: &#x22;Present when the field is in edit mode&#x22;,
  },
]"
/>

### EditablePreview [#editablepreview]

The preview component that displays the current value.

<AutoTypeTable path="./types/base/editable.ts" name="EditablePreviewProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-empty]&#x22;,
    value: &#x22;Present when the field has no value&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the field is read-only&#x22;,
  },
]"
/>

### EditableInput [#editableinput]

The input component for editing the value.

<AutoTypeTable path="./types/base/editable.ts" name="EditableInputProps" />

### EditableTrigger [#editabletrigger]

Button to trigger edit mode.

<AutoTypeTable path="./types/base/editable.ts" name="EditableTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the field is read-only&#x22;,
  },
]"
/>

### EditableToolbar [#editabletoolbar]

Container for action buttons.

<AutoTypeTable path="./types/base/editable.ts" name="EditableToolbarProps" />

### EditableSubmit [#editablesubmit]

Button to submit changes.

<AutoTypeTable path="./types/base/editable.ts" name="EditableSubmitProps" />

### EditableCancel [#editablecancel]

Button to cancel changes.

<AutoTypeTable path="./types/base/editable.ts" name="EditableCancelProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Submits the current value when in edit mode.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Cancels editing and reverts to the previous value.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
]"
/>


# Faceted
URL: /docs/components/base/faceted



<ComponentTabs name="faceted-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils cmdk
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils cmdk
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils cmdk
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils cmdk
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Install the command and popover components from shadcn/ui.
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npx shadcn@latest add command popover
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm dlx shadcn@latest add command popover
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn dlx shadcn@latest add command popover
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun x shadcn@latest add command popover
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="faceted" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  Faceted,
  FacetedClear,
  FacetedContent,
  FacetedEmpty,
  FacetedGroup,
  FacetedInput,
  FacetedItem,
  FacetedItemIndicator,
  FacetedList,
  FacetedLoading,
  FacetedTrigger,
  FacetedValue,
} from "@/components/ui/faceted";

return (
  <Faceted>
    <FacetedTrigger>
      <FacetedValue />
    </FacetedTrigger>
    <FacetedContent>
      <FacetedInput />
      <FacetedList>
        <FacetedLoading />
        <FacetedEmpty />
        <FacetedGroup>
          <FacetedItem>
            <FacetedItemIndicator />
          </FacetedItem>
        </FacetedGroup>
        <FacetedClear />
      </FacetedList>
    </FacetedContent>
  </Faceted>
)
```

## Examples [#examples]

### Multiple [#multiple]

Set `multiple` to select more than one value. `FacetedItemIndicator` can show a count until the item is selected, and `FacetedClear` appears once something is selected.

<ComponentTabs name="faceted-multiple-demo" />

### Groups [#groups]

Split items into groups with headings, and separate them with `FacetedSeparator`.

<ComponentTabs name="faceted-groups-demo" />

### Async [#async]

Search on the server by setting `shouldFilter={false}` on `FacetedContent` and controlling the search with `value` and `onValueChange` on `FacetedInput`. Show `FacetedLoading` while a request is pending. Keep the selected options in `items` so their badges stay labeled when they aren't in the current results.

<ComponentTabs name="faceted-async-demo" />

### Controlled [#controlled]

Control the selection with `value` and `onValueChange`.

<ComponentTabs name="faceted-controlled-demo" />

## API Reference [#api-reference]

### Faceted [#faceted]

The root component. It holds the selection and the popover's open state.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedProps" />

### FacetedTrigger [#facetedtrigger]

The button that opens the popover. Use `render` to render your own button.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedTriggerProps" />

### FacetedValue [#facetedvalue]

Shows the current selection inside the trigger, as badges or a placeholder. Labels come from the `items` passed to `Faceted`.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedValueProps" />

### FacetedBadgeList [#facetedbadgelist]

The container for the selection badges.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedBadgeListProps" />

### FacetedBadge [#facetedbadge]

A badge for one selected option.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedBadgeProps" />

### FacetedContent [#facetedcontent]

The popover content. It wraps its children in a command menu.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedContentProps" />

### FacetedInput [#facetedinput]

The search input that filters the items. Set `variant="line"` for a plain row with a divider below it.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedInputProps" />

### FacetedList [#facetedlist]

The scrollable list of groups and items.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedListProps" />

### FacetedEmpty [#facetedempty]

Shown when no items match the search.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedEmptyProps" />

### FacetedLoading [#facetedloading]

Shown while results are loading, such as during a server search.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedLoadingProps" />

### FacetedGroup [#facetedgroup]

A group of items with an optional heading.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedGroupProps" />

### FacetedItem [#faceteditem]

A selectable option.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-checked]&#x22;,
    value: &#x22;Present when the item is selected.&#x22;,
  },
  {
    title: &#x22;[data-selected]&#x22;,
    value: &#x22;Present when the item is highlighted.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
]"
/>

### FacetedItemIndicator [#faceteditemindicator]

The check shown on selected items. Its children, such as a count, show while the item isn't selected.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedItemIndicatorProps" />

### FacetedClear [#facetedclear]

An item that clears the selection, in its own group below a separator. It only renders when something is selected.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedClearProps" />

### FacetedSeparator [#facetedseparator]

A line between groups.

<AutoTypeTable path="./types/base/faceted.ts" name="FacetedSeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;When focus is on the trigger, opens the popover.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves the highlight to the next or previous item.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;, &#x22;End&#x22;],
    description: &#x22;Moves the highlight to the first or last item.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Selects or deselects the highlighted item.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the popover and returns focus to the trigger.&#x22;,
  },
]"
/>


# File Upload
URL: /docs/components/base/file-upload



<ComponentTabs name="file-upload-demo" align="start" className="p-8" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the direction utilities into your 

        `components/direction.tsx`

         file.
      </Step>

      <ComponentSource name="direction" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="file-upload" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadTrigger,
  FileUploadList,
  FileUploadItem,
  FileUploadItemPreview,
  FileUploadItemMetadata,
  FileUploadItemProgress,
  FileUploadItemDelete,
  FileUploadClear,
} from "@/components/ui/file-upload";

return (
  <FileUpload>
    <FileUploadDropzone />
    <FileUploadTrigger />
    <FileUploadList>
      <FileUploadItem>
        <FileUploadItemPreview />
        <FileUploadItemMetadata />
        <FileUploadItemProgress />
        <FileUploadItemDelete />
      </FileUploadItem>
    </FileUploadList>
    <FileUploadClear />
  </FileUpload>
)
```

## Examples [#examples]

### With Validation [#with-validation]

Validate files with the `onFileValidate` prop on the `Root` component based on type, size, and custom rules. This will override the default file rejection message.

<ComponentTabs name="file-upload-validation-demo" align="start" className="p-8" />

### Direct Upload [#direct-upload]

Upload files directly with the `onUpload` prop on the `Root` component.

<ComponentTabs name="file-upload-direct-upload-demo" align="start" className="p-8" />

### Circular Progress [#circular-progress]

Render a circular progress indicator instead of a linear one by enabling the `circular` prop on the `ItemProgress` component.

<ComponentTabs name="file-upload-circular-progress-demo" align="start" />

### Fill Progress [#fill-progress]

Render a fill progress indicator instead of a linear one by enabling the `fill` prop on the `ItemProgress` component.

<ComponentTabs name="file-upload-fill-progress-demo" align="start" />

### With uploadthing [#with-uploadthing]

Integrate with [uploadthing](https://uploadthing.com) for secure, type-safe file uploads with real-time progress tracking.

<ComponentTabs name="file-upload-uploadthing-demo" align="start" className="p-8" />

### With Chat Input [#with-chat-input]

Integrate into a chat input for uploading files. For demo the `Dropzone` is absolutely positioned to cover the entire viewport.

<ComponentTabs name="file-upload-chat-input-demo" align="start" />

### With Form [#with-form]

Use the `value` and `onValueChange` props to handle file uploads with validation and submission.

<ComponentTabs name="file-upload-form-demo" align="start" className="p-8" />

## API Reference [#api-reference]

### FileUpload [#fileupload]

The main container component for the file upload functionality.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadProps" />

### FileUploadDropzone [#fileuploaddropzone]

A container for drag and drop functionality.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadDropzoneProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the dropzone is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when files are being dragged over the dropzone.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when there was an error with the files being uploaded.&#x22;,
  },
]"
/>

### FileUploadTrigger [#fileuploadtrigger]

A button that opens the file selection dialog.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the trigger is disabled.&#x22;,
  }
]"
/>

### FileUploadList [#fileuploadlist]

A container for displaying uploaded files.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
]"
/>

### FileUploadItem [#fileuploaditem]

Individual file item component.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadItemProps" />

### FileUploadItemPreview [#fileuploaditempreview]

Displays a preview of the file, showing an image for image files or an appropriate icon for other file types.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadItemPreviewProps" />

### FileUploadItemMetadata [#fileuploaditemmetadata]

Displays file information such as name, size, and error messages.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadItemMetadataProps" />

### FileUploadItemProgress [#fileuploaditemprogress]

Shows the upload progress for a file.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadItemProgressProps" />

### FileUploadItemDelete [#fileuploaditemdelete]

A button to remove a file from the list.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadItemDeleteProps" />

### FileUploadClear [#fileuploadclear]

A button to clear all files from the list.

<AutoTypeTable path="./types/base/file-upload.ts" name="FileUploadClearProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the clear button is disabled.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;When focus is on the dropzone or trigger, opens the file selection dialog.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus between the dropzone, trigger, and file delete buttons.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;When the dropzone is focused, moves focus away from the dropzone.&#x22;,
  },
]"
/>

## Credits [#credits]

* [Building a Hold to Delete Component](https://emilkowal.ski/ui/building-a-hold-to-delete-component) - For the fill progress indicator.


# FPS
URL: /docs/components/base/fps



<ComponentTabs name="fps-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="fps" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Examples [#examples]

### Positioning Strategy [#positioning-strategy]

Control whether the FPS counter uses `fixed` or `absolute` positioning.

<ComponentTabs name="fps-strategy-demo" />

### Custom Position [#custom-position]

Choose from four corner positions for the FPS counter.

```tsx
import { Fps } from "@/components/fps"

export default function App() {
  return (
    <div>
      <Fps position="bottom-left" />
      {/* Your app content */}
    </div>
  )
}
```

### Custom Thresholds [#custom-thresholds]

Configure warning and error thresholds for color-coded performance indicators.

```tsx
import { Fps } from "@/components/fps"

export default function App() {
  return (
    <div>
      <Fps 
        warningThreshold={45}
        errorThreshold={30}
      />
      {/* Your app content */}
    </div>
  )
}
```

### Conditional Rendering [#conditional-rendering]

Enable the FPS counter only in development environments.

```tsx
import { Fps } from "@/components/fps"

export default function App() {
  const isDevelopment = process.env.NODE_ENV === "development"
  
  return (
    <div>
      <Fps enabled={isDevelopment} />
      {/* Your app content */}
    </div>
  )
}
```

## API Reference [#api-reference]

### Fps [#fps]

A component that displays a real-time FPS counter overlay.

<AutoTypeTable path="./types/base/fps.ts" name="FpsProps" />

## Features [#features]

* **Real-time monitoring**: Uses `requestAnimationFrame` for accurate FPS measurement
* **Color-coded display**: Automatically changes color based on performance thresholds
  * Green: Good performance (above warning threshold)
  * Yellow: Warning (below warning threshold)
  * Red: Poor performance (below error threshold)
* **Flexible positioning**: Choose between `fixed` and `absolute` positioning strategies
* **Customizable position**: Choose from four corner positions
* **Configurable update interval**: Control how often the FPS value updates
* **Performance optimized**: Minimal overhead with efficient frame counting

## Positioning Strategies [#positioning-strategies]

### Fixed Positioning [#fixed-positioning]

When using `strategy="fixed"`, the FPS counter is positioned relative to the viewport and rendered via a portal into the document body. This is useful when you want the counter to remain visible while scrolling.

```tsx
<Fps strategy="fixed" position="top-right" />
```

### Absolute Positioning [#absolute-positioning]

When using `strategy="absolute"`, the FPS counter is rendered directly in place (without a portal) and positioned relative to its nearest positioned ancestor. This is useful when you want the counter to be contained within a specific element with a `relative` wrapper.

```tsx
<div className="relative">
  <Fps strategy="absolute" position="bottom-left" />
</div>
```

**Note:** Unlike `fixed` positioning, `absolute` positioning does not use a portal, so the component will respect relative positioning contexts and be contained within its parent element.

## Performance Considerations [#performance-considerations]

The FPS counter uses `requestAnimationFrame` to measure frame rate, which has minimal performance impact. The component:

* Only updates the display at the specified interval (default: 500ms)
* Uses refs to avoid unnecessary re-renders
* Automatically cleans up animation frames on unmount

For production builds, consider disabling the FPS counter:

```tsx
<Fps enabled={process.env.NODE_ENV === "development"} />
```


# Gauge
URL: /docs/components/base/gauge



<ComponentTabs name="gauge-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="gauge" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  Gauge,
  GaugeIndicator,
  GaugeTrack,
  GaugeRange,
  GaugeValueText,
  GaugeLabel,
} from "@/components/ui/gauge";

return (
  <Gauge>
    <GaugeIndicator>
      <GaugeTrack />
      <GaugeRange />
    </GaugeIndicator>
    <GaugeValueText />
    <GaugeLabel>Label</GaugeLabel>
  </Gauge>
)
```

Or use the `Combined` component to get all the parts in one.

```tsx
import { GaugeCombined } from "@/components/ui/gauge";

<GaugeCombined label="Performance" />
```

## Examples [#examples]

### Sizes [#sizes]

Different gauge sizes to fit various UI contexts.

<ComponentTabs name="gauge-sizes-demo" />

### Colors [#colors]

Different color themes for various use cases like system monitoring, health indicators, and status displays.

<ComponentTabs name="gauge-colors-demo" />

### Variants [#variants]

Different arc configurations including semi-circle, three-quarter circle, and full circle gauges.

<ComponentTabs name="gauge-variants-demo" />

## Value Text Formatting [#value-text-formatting]

By default, the gauge displays the percentage value (0–100) based on `value`, `min`, and `max`. You can customize the format using the `getValueText` prop:

### Show Percentage [#show-percentage]

```tsx
<Gauge 
  value={85}
  getValueText={(value, min, max) => {
    const percentage = ((value - min) / (max - min)) * 100;
    return `${Math.round(percentage)}%`;
  }}
>
  {/* ... */}
</Gauge>
```

### Show Fraction [#show-fraction]

```tsx
<Gauge 
  value={75}
  max={100}
  getValueText={(value, min, max) => `${value}/${max}`}
>
  {/* ... */}
</Gauge>
```

### Custom Text [#custom-text]

```tsx
<Gauge 
  value={75}
  getValueText={(value) => `${value} points`}
>
  {/* ... */}
</Gauge>
```

## Theming [#theming]

The gauge component uses CSS `currentColor` for stroke colors, making it easy to theme using Tailwind's text utilities:

### Track Theming [#track-theming]

```tsx
<GaugeTrack className="text-blue-200 dark:text-blue-900" />
```

### Range Theming [#range-theming]

```tsx
<GaugeRange className="text-blue-500" />
```

### Value Text Theming [#value-text-theming]

```tsx
<GaugeValueText className="text-blue-700 dark:text-blue-300" />
```

### Label Theming [#label-theming]

```tsx
<GaugeLabel className="text-blue-600" />
```

## API Reference [#api-reference]

### Gauge [#gauge]

The main container component for the gauge.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current gauge value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized gauge value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### GaugeIndicator [#gaugeindicator]

The SVG container that holds the gauge arc paths.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current gauge value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized gauge value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### GaugeTrack [#gaugetrack]

The background arc that represents the full range of possible values.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeTrackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### GaugeRange [#gaugerange]

The portion of the arc that represents the current gauge value with smooth animations.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeRangeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current gauge value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum gauge value.&#x22;,
  },
]"
/>

### GaugeValueText [#gaugevaluetext]

The text element that displays the current gauge value or custom content. Automatically centers within the arc's visual bounds.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeValueTextProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### GaugeLabel [#gaugelabel]

An optional label element that displays below the gauge.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeLabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### GaugeCombined [#gaugecombined]

The combined component that includes all the parts.

<AutoTypeTable path="./types/base/gauge.ts" name="GaugeProps" />

## Accessibility [#accessibility]

### Screen Reader Support [#screen-reader-support]

* Uses the `meter` role for proper screen reader identification
* Provides `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` attributes
* Supports `aria-labelledby` when a label prop is provided
* Supports indeterminate state by omitting `aria-valuenow` when value is null

## Notes [#notes]

* The component automatically handles indeterminate states when `value` is `null` or `undefined`
* Gauge values are automatically clamped to the valid range between `min` and `max`
* Invalid `max` or `value` props will log console errors and use fallback values
* Supports full circles (360°) by automatically splitting into two semi-circles for proper SVG rendering
* Value text automatically centers within the arc's visual bounds for both full and partial circles
* The gauge range uses `stroke-dashoffset` animations for smooth, performant filling effects
* All stroke colors use `currentColor` by default, making them responsive to text color changes
* Default angles are 0° (start) to 360° (end) for a full circle gauge


# Kanban
URL: /docs/components/base/kanban



<ComponentTabs name="kanban-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="kanban" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnHandle,
  KanbanItem,
  KanbanItemHandle,
  KanbanOverlay,
} from "@/components/ui/kanban";

return (
  <Kanban>
    <KanbanBoard>
      <KanbanColumn>
        <KanbanColumnHandle />
        <KanbanItem>
          <KanbanItemHandle />
        </KanbanItem>
      </KanbanColumn>
    </KanbanBoard>
    <KanbanOverlay />
  </Kanban>
)
```

Every part accepts a `render` prop, so a column or item can be composed with your own element or component instead of the default `div`.

```tsx
<KanbanColumnHandle render={<Button variant="ghost" size="icon" />}>
  <GripVertical />
</KanbanColumnHandle>
```

## Usage [#usage]

### With Primitive Values [#with-primitive-values]

When using primitive arrays (strings, numbers), the `getItemValue` prop is optional. The component will automatically use the items themselves as unique identifiers.

```tsx
const [columns, setColumns] = React.useState({
  todo: ["Task 1", "Task 2"],
  done: ["Task 3"],
});

<Kanban value={columns} onValueChange={setColumns}>
  <KanbanBoard>
    {Object.entries(columns).map(([columnValue, items]) => (
      <KanbanColumn key={columnValue} value={columnValue}>
        {items.map((item) => (
          <KanbanItem key={item} value={item}>
            {item}
          </KanbanItem>
        ))}
      </KanbanColumn>
    ))}
  </KanbanBoard>
</Kanban>
```

### With Object Arrays [#with-object-arrays]

When using object arrays, the `getItemValue` prop is required to extract unique identifiers from each item.

```tsx
const [columns, setColumns] = React.useState({
  todo: [
    { id: 1, title: "Task 1" },
    { id: 2, title: "Task 2" },
  ],
  done: [
    { id: 3, title: "Task 3" },
  ],
});

<Kanban
  value={columns}
  onValueChange={setColumns}
  getItemValue={(item) => item.id}
>
  <KanbanBoard>
    {Object.entries(columns).map(([columnValue, items]) => (
      <KanbanColumn key={columnValue} value={columnValue}>
        {items.map((item) => (
          <KanbanItem key={item.id} value={item.id}>
            {item.title}
          </KanbanItem>
        ))}
      </KanbanColumn>
    ))}
  </KanbanBoard>
</Kanban>
```

## Examples [#examples]

### With Dynamic Overlay [#with-dynamic-overlay]

Display a dynamic overlay when an item or column is being dragged.

<ComponentTabs name="kanban-dynamic-overlay-demo" />

## API Reference [#api-reference]

### Kanban [#kanban]

The main container component for kanban board functionality.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanProps" />

### KanbanBoard [#kanbanboard]

Container for kanban columns.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanBoardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### KanbanColumn [#kanbancolumn]

Individual kanban column component.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanColumnProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the column is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the column is being dragged.&#x22;,
  },
]"
/>

### KanbanColumnHandle [#kanbancolumnhandle]

A button component that acts as a drag handle for kanban columns.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanColumnHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the column is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the parent column is being dragged.&#x22;,
  }
]"
/>

### KanbanItem [#kanbanitem]

Individual kanban item component.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the item is being dragged.&#x22;,
  },
]"
/>

### KanbanItemHandle [#kanbanitemhandle]

A button component that acts as a drag handle for kanban items.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanItemHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the parent item is being dragged.&#x22;,
  }
]"
/>

### KanbanOverlay [#kanbanoverlay]

The overlay component that appears when an item or column is being dragged.

<AutoTypeTable path="./types/base/kanban.ts" name="KanbanOverlayProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Picks up the kanban item or column for reordering when released, and drops it in its new position when pressed again.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves the kanban item up in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves the kanban item down in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves the kanban item left in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves the kanban item right in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;Esc&#x22;],
    description: &#x22;Cancels the drag operation and returns the item or column to its original position.&#x22;,
  },
]"
/>


# Kbd
URL: /docs/components/base/kbd



<Callout type="warn">
  **Deprecated.** Kbd was removed from Dice UI in October 2025. shadcn/ui ships a [Kbd](https://ui.shadcn.com/docs/components/base/kbd) component, so use that instead:

  <CodeBlockTabs defaultValue="npm" groupId="package-manager">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npx shadcn@latest add kbd
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm dlx shadcn@latest add kbd
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn dlx shadcn@latest add kbd
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun x shadcn@latest add kbd
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</Callout>

## Migrating [#migrating]

`@diceui/kbd` no longer installs. Replace it with shadcn/ui's `Kbd` and `KbdGroup`:

| Dice UI                            | shadcn/ui                                  |
| ---------------------------------- | ------------------------------------------ |
| `Kbd.Root` / `KbdRoot`             | `KbdGroup`                                 |
| `Kbd.Key` / `KbdKey`               | `Kbd`                                      |
| `Kbd.Separator` / `KbdSeparator`   | Text between keys, such as `+`, or nothing |
| `title` on `Kbd.Key`               | Wrap the key in `<abbr title="…">`         |
| `variant` and `size` on `Kbd.Root` | `className`                                |

```tsx
import * as Kbd from "@/components/ui/kbd"; // [!code --]
import { Kbd, KbdGroup } from "@/components/ui/kbd"; // [!code ++]

// Before
<Kbd.Root>
  <Kbd.Key>⌘</Kbd.Key>
  <Kbd.Separator />
  <Kbd.Key>K</Kbd.Key>
</Kbd.Root>

// After
<KbdGroup>
  <Kbd>
    <abbr title="Command">⌘</abbr>
  </Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

`Kbd.Key` added a `title` for common symbols such as ⌘, ⇧ and ⌥ automatically. shadcn/ui's `Kbd` doesn't, so add an `<abbr title>` where a symbol needs a description.


# Key Value
URL: /docs/components/base/key-value



<ComponentTabs name="key-value-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="key-value" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  KeyValue,
  KeyValueList,
  KeyValueItem,
  KeyValueKeyInput,
  KeyValueValueInput,
  KeyValueRemove,
  KeyValueError,
  KeyValueAdd,
} from "@/components/ui/key-value";

return (
  <KeyValue>
    <KeyValueList>
      <KeyValueItem>
        <KeyValueKeyInput />
        <KeyValueValueInput />
        <KeyValueRemove />
        <KeyValueError field="key" />
        <KeyValueError field="value" />
      </KeyValueItem>
    </KeyValueList>
    <KeyValueAdd />
  </KeyValue>
)
```

## Examples [#examples]

### With Paste Support [#with-paste-support]

Paste multiple key-value pairs at once. Supports formats like `KEY=VALUE`, `KEY: VALUE`, and tab-separated values.

<ComponentTabs name="key-value-paste-demo" />

### With Validation [#with-validation]

Add validation rules for keys and values with error messages.

<ComponentTabs name="key-value-validation-demo" />

### With Form [#with-form]

Integrate with React Hook Form for form validation.

<ComponentTabs name="key-value-form-demo" />

## API Reference [#api-reference]

### KeyValue [#keyvalue]

The main container component that manages the key-value items state.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when any item has validation errors&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when read-only&#x22;,
  },
]"
/>

### KeyValueList [#keyvaluelist]

Container for rendering the list of key-value items.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: &#x22;vertical | horizontal&#x22;,
  },
]"
/>

### KeyValueItem [#keyvalueitem]

Individual key-value pair item container.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when item is highlighted/focused&#x22;,
  },
]"
/>

### KeyInput [#keyinput]

Input field for the key part of the item.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueKeyInputProps" />

### ValueInput [#valueinput]

Input field for the value part of the item.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueValueInputProps" />

### KeyValueRemove [#keyvalueremove]

Button to remove a key-value item.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueRemoveProps" />

### KeyValueAdd [#keyvalueadd]

Button to add a new key-value item.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueAddProps" />

### KeyValueError [#keyvalueerror]

Error message display for validation errors.

<AutoTypeTable path="types/base/key-value.ts" name="KeyValueErrorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Navigate between key inputs, value inputs, and buttons.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Submit the current input value.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Cancel the current input.&#x22;,
  },
  {
    keys: [&#x22;Ctrl&#x22;, &#x22;V&#x22;],
    description: &#x22;Paste multiple key-value pairs (supports multiple formats).&#x22;,
  },
]"
/>

## Features [#features]

* **Dynamic Items**: Add and remove key-value pairs dynamically
* **Paste Support**: Paste multiple items at once in various formats (`KEY=VALUE`, `KEY: VALUE`, tab-separated)
* **Validation**: Built-in validation for keys and values with custom validators
* **Duplicate Detection**: Optional prevention of duplicate keys
* **Item Limits**: Set minimum and maximum item counts
* **Form Integration**: Works seamlessly with React Hook Form
* **Controlled/Uncontrolled**: Supports both controlled and uncontrolled patterns
* **Accessibility**: Full keyboard navigation and screen reader support
* **Customizable**: Fully customizable styling and behavior

## Paste Formats [#paste-formats]

The component supports pasting multiple key-value pairs in the following formats:

```
KEY=VALUE
DATABASE_URL=postgresql://localhost:5432
API_KEY=sk-1234567890

KEY: VALUE
DATABASE_URL: postgresql://localhost:5432
API_KEY: sk-1234567890

KEY	VALUE (tab-separated)
DATABASE_URL	postgresql://localhost:5432
API_KEY	sk-1234567890
```

When pasting multiple lines, the component will automatically parse and create separate items for each line.


# Listbox
URL: /docs/components/base/listbox



<ComponentTabs name="listbox-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/listbox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/listbox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/listbox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/listbox
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/listbox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/listbox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/listbox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/listbox
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="listbox" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ListboxRoot,
  ListboxGroup,
  ListboxGroupLabel,
  ListboxItem,
  ListboxItemIndicator,
} from "@diceui/listbox"

return (
  <ListboxRoot>
    <ListboxGroup>
      <ListboxGroupLabel/>
      <ListboxItem >
        <ListboxItemIndicator />
      </ListboxItem>
    </ListboxGroup>
  </ListboxRoot>
)
```

## Examples [#examples]

### Horizontal Orientation [#horizontal-orientation]

Set `orientation="horizontal"` to create a horizontally navigable list.

<ComponentTabs name="listbox-horizontal-demo" />

### Grid Layout [#grid-layout]

For grid layouts, use `orientation="mixed"` to enable navigation in both directions.
Use CSS Grid to arrange the items in a grid structure. In grid layouts,
arrow keys will navigate accordingly:

* Up/Down: Navigates within a column
* Left/Right: Navigates within a row

<ComponentTabs name="listbox-grid-demo" />

### Grouped Items [#grouped-items]

Group items together to create a list of related options.

<ComponentTabs name="listbox-group-demo" />

## API Reference [#api-reference]

### Listbox [#listbox]

The root component for creating listboxes.

<AutoTypeTable path="./types/base/listbox.ts" name="RootProps" />

### ListboxGroup [#listboxgroup]

A group of items inside the selectable list.

<AutoTypeTable path="./types/base/listbox.ts" name="GroupProps" />

### ListboxGroupLabel [#listboxgrouplabel]

A label for the group of items.

<AutoTypeTable path="./types/base/listbox.ts" name="GroupLabelProps" />

### ListboxItem [#listboxitem]

An item inside the selectable list.

<AutoTypeTable path="./types/base/listbox.ts" name="ItemProps" />

### ListboxItemIndicator [#listboxitemindicator]

A visual indicator that shows when the item is selected.

<AutoTypeTable path="./types/base/listbox.ts" name="ItemIndicatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Focuses the last active item in the list.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to previous focusable item in the list.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves highlighting to previous item in vertical lists.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves highlighting to next item in vertical lists.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves highlighting to previous item in horizontal lists.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves highlighting to next item in horizontal lists.&#x22;,
  },
]"
/>


# Marquee
URL: /docs/components/base/marquee



<ComponentTabs name="marquee-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/marquee"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/marquee"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/marquee"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/marquee"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="marquee" />

      <Step>
        Add the following CSS animations to your 

        `globals.css`

         file:
      </Step>

      ```css
      :root {
        --animate-marquee-left: marquee-left var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-right: marquee-right var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-left-rtl: marquee-left-rtl var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-right-rtl: marquee-right-rtl var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-up: marquee-up var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-down: marquee-down var(--marquee-duration) linear var(--marquee-loop-count);

      @keyframes marquee-left {
        0% {
          transform: translateX(0%);
        }
        100% {
          transform: translateX(calc(-100% - var(--marquee-gap)));
        }
      }

      @keyframes marquee-right {
        0% {
          transform: translateX(calc(-100% - var(--marquee-gap)));
        }
        100% {
          transform: translateX(0%);
        }
      }

      @keyframes marquee-up {
        0% {
          transform: translateY(0%);
        }
        100% {
          transform: translateY(calc(-100% - var(--marquee-gap)));
        }
      }

      @keyframes marquee-down {
        0% {
          transform: translateY(calc(-100% - var(--marquee-gap)));
        }
        100% {
          transform: translateY(0%);
        }
      }

      @keyframes marquee-left-rtl {
        0% {
          transform: translateX(0%);
        }
        100% {
          transform: translateX(calc(100% + var(--marquee-gap)));
        }
      }

      @keyframes marquee-right-rtl {
        0% {
          transform: translateX(calc(100% + var(--marquee-gap)));
        }
        100% {
          transform: translateX(0%);
        }
      }
      }
      ```
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import * as Marquee from "@/components/ui/marquee"

return (
  <Marquee.Root>
    <Marquee.Content>
      <Marquee.Item />
    </Marquee.Content>
    <Marquee.Edge side="left" />
    <Marquee.Edge side="right" />
  </Marquee.Root>
)
```

## Examples [#examples]

### Logo Showcase [#logo-showcase]

Use the marquee to showcase logos or brands in a continuous scroll.

<ComponentTabs name="marquee-logo-demo" />

### Vertical Layout [#vertical-layout]

Use `side` to control the direction of the marquee.

<ComponentTabs name="marquee-vertical-demo" />

### With RTL [#with-rtl]

The marquee component automatically adapts to RTL (right-to-left) layouts.

<ComponentTabs name="marquee-rtl-demo" />

## API Reference [#api-reference]

### Marquee [#marquee]

The main marquee component that creates continuous scrolling animations.

<AutoTypeTable path="./types/base/marquee.ts" name="MarqueeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--marquee-duration&#x22;,
    description: &#x22;The duration of the marquee animation in seconds. Calculated based on content size and speed.&#x22;,
    defaultValue: &#x22;Calculated dynamically (e.g., 20s)&#x22;,
  },
  {
    title: &#x22;--marquee-gap&#x22;,
    description: &#x22;The gap between marquee items and repetitions.&#x22;,
    defaultValue: &#x22;1rem&#x22;,
  },
  {
    title: &#x22;--marquee-delay&#x22;,
    description: &#x22;The delay before the marquee animation starts in seconds.&#x22;,
    defaultValue: &#x22;0s&#x22;,
  },
  {
    title: &#x22;--marquee-loop-count&#x22;,
    description: &#x22;The number of times the animation should repeat. Can be a number or 'infinite'.&#x22;,
    defaultValue: &#x22;infinite&#x22;,
  },
]"
/>

### MarqueeContent [#marqueecontent]

Contains the scrolling content and handles repetition for seamless animation.

<AutoTypeTable path="./types/base/marquee.ts" name="MarqueeContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### MarqueeItem [#marqueeitem]

Individual items within the marquee content.

<AutoTypeTable path="./types/base/marquee.ts" name="MarqueeItemProps" />

### MarqueeEdge [#marqueeedge]

Edge overlay components for smooth gradient transitions.

<AutoTypeTable path="./types/base/marquee.ts" name="MarqueeEdgeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-size]&#x22;,
    value: [&#x22;default&#x22;, &#x22;sm&#x22;, &#x22;lg&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Pauses or resumes the marquee animation when pauseOnKeyboard is enabled.&#x22;,
  },
]"
/>

## Features [#features]

* **RTL Support**: Automatically adapts to RTL (right-to-left) layouts
* **Screen Reader Support**: Content remains accessible to assistive technologies
* **Reduced Motion**: Respects user's `prefers-reduced-motion` setting
* **Pause Controls**:
  * **Hover**: Can be configured to pause animation when hovered
  * **Keyboard**: Press Space key to pause/resume (when `pauseOnKeyboard` is enabled)
* **Focus Management**: Proper focus indicators and keyboard navigation when `pauseOnKeyboard` is enabled


# Mask Input
URL: /docs/components/base/mask-input



<ComponentTabs name="mask-input-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="mask-input" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import and use the component directly.

```tsx
import { MaskInput } from "@/components/ui/mask-input";

<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
  maskPlaceholder="(___) ___-____"
  onValueChange={(masked, unmasked) => {
    console.log('Masked:', masked);     // "(555) 123-4567"
    console.log('Unmasked:', unmasked); // "5551234567"
  }}
/>
```

## Features [#features]

* **Smart cursor positioning** - Cursor stays in the correct position during typing and pasting
* **Paste support** - Intelligently handles pasted content with proper formatting
* **Built-in patterns** - Common formats like phone, SSN, date, credit card, etc.
* **Custom patterns** - Create your own mask patterns with validation
* **Optional mask placeholders** - Control when mask format hints are shown with `maskPlaceholder`
* **TypeScript support** - Full type safety with IntelliSense
* **Accessibility** - ARIA attributes and keyboard navigation
* **Form integration** - Works seamlessly with form libraries
* **Composition support** - Use `render` prop to render as a different component

## Examples [#examples]

### With custom patterns [#with-custom-patterns]

Create custom mask patterns for specific formatting needs.

<ComponentTabs name="mask-input-custom-pattern-demo" />

### With validation modes [#with-validation-modes]

Control when validation occurs with different validation modes, similar to react-hook-form.

<ComponentTabs name="mask-input-validation-modes-demo" />

### Card information [#card-information]

Card information with credit card number, expiry date, and CVC fields.

<ComponentTabs name="mask-input-card-information-demo" />

### With form [#with-form]

Integrate masked inputs with form validation using react-hook-form.

<ComponentTabs name="mask-input-form-demo" />

## Built-in Mask Patterns [#built-in-mask-patterns]

The component includes several predefined mask patterns:

| Pattern            | Format                | Example             | Description                                 |
| ------------------ | --------------------- | ------------------- | ------------------------------------------- |
| `phone`            | `(###) ###-####`      | (555) 123-4567      | US phone number                             |
| `ssn`              | `###-##-####`         | 123-45-6789         | Social Security Number                      |
| `date`             | `##/##/####`          | 12/25/2023          | Date (MM/DD/YYYY)                           |
| `time`             | `##:##`               | 14:30               | Time (HH:MM)                                |
| `creditCard`       | `#### #### #### ####` | 1234 5678 9012 3456 | Credit card number                          |
| `creditCardExpiry` | `##/##`               | 12/25               | Credit card expiry date (MM/YY)             |
| `zipCode`          | `#####`               | 12345               | US ZIP code                                 |
| `zipCodeExtended`  | `#####-####`          | 12345-6789          | US ZIP+4 code                               |
| `currency`         | Dynamic               | \$1,234.56          | Currency formatting using Intl.NumberFormat |
| `percentage`       | `##.##%`              | 12.34%              | Percentage with decimals                    |
| `licensePlate`     | `###-###`             | ABC-123             | License plate format                        |
| `ipv4`             | `###.###.###.###`     | 192.168.1.1         | IPv4 address                                |
| `macAddress`       | `##:##:##:##:##:##`   | 00:1B:44:11:3A:B7   | MAC address                                 |
| `isbn`             | `###-#-###-#####-#`   | 978-0-123-45678-9   | ISBN-13 book identifier                     |
| `ein`              | `##-#######`          | 12-3456789          | Employer Identification Number              |

## Custom Mask Patterns [#custom-mask-patterns]

Create custom patterns using the `MaskPattern` interface:

```tsx
const customPattern: MaskPattern = {
  pattern: "###-###-####",
  transform: (value, opts) => value.replace(/[^A-Z0-9]/gi, "").toUpperCase(),
  validate: (value, opts) => value.length === 10,
};

<MaskInput 
  mask={customPattern} 
  placeholder="Enter license plate"
  maskPlaceholder="ABC-1234"
/>
```

## Currency Formatting [#currency-formatting]

The currency mask uses the `Intl.NumberFormat` API for localization and currency formatting.

```tsx
// Default USD formatting
<MaskInput mask="currency" />

// Euro formatting with German locale
<MaskInput 
  mask="currency" 
  currency="EUR" 
  locale="de-DE" 
/>

// Japanese Yen formatting
<MaskInput 
  mask="currency" 
  currency="JPY" 
  locale="ja-JP" 
/>

// British Pound formatting
<MaskInput 
  mask="currency" 
  currency="GBP" 
  locale="en-GB" 
/>
```

## Mask Placeholders [#mask-placeholders]

Use the `maskPlaceholder` prop to control when mask format hints are shown. The mask placeholder only appears when the input is focused and the prop is provided.

```tsx
// Shows mask placeholder when focused
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
  maskPlaceholder="(___) ___-____"
/>

// No mask placeholder - just regular placeholder behavior
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
/>
```

## API Reference [#api-reference]

### MaskInput [#maskinput]

The main masked input component that handles formatting and user input.

<AutoTypeTable path="./types/base/mask-input.ts" name="MaskInputProps" />

### MaskPattern [#maskpattern]

Interface for creating custom mask patterns.

<AutoTypeTable path="./types/base/mask-input.ts" name="MaskPattern" />

### MaskPatternKey [#maskpatternkey]

Predefined mask pattern keys for common input formats.

| Pattern            | Description                                 |
| ------------------ | ------------------------------------------- |
| `phone`            | US phone number                             |
| `ssn`              | Social Security Number                      |
| `date`             | Date (MM/DD/YYYY)                           |
| `time`             | Time (HH:MM)                                |
| `creditCard`       | Credit card number                          |
| `creditCardExpiry` | Credit card expiry date (MM/YY)             |
| `zipCode`          | US ZIP code                                 |
| `zipCodeExtended`  | US ZIP+4 code                               |
| `currency`         | Currency formatting using Intl.NumberFormat |
| `percentage`       | Percentage with decimals                    |
| `licensePlate`     | License plate format                        |
| `ipv4`             | IPv4 address                                |
| `macAddress`       | MAC address                                 |
| `isbn`             | ISBN-13 book identifier                     |
| `ein`              | Employer Identification Number              |

### TransformOptions [#transformoptions]

Options passed to the transform function for advanced formatting.

<AutoTypeTable path="./types/base/mask-input.ts" name="TransformOptions" />

### ValidateOptions [#validateoptions]

Options passed to the validate function for enhanced validation.

<AutoTypeTable path="./types/base/mask-input.ts" name="ValidateOptions" />

## Data Attributes [#data-attributes]

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the input is disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the input has validation errors.&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the input is read-only.&#x22;,
  },
  {
    title: &#x22;[data-required]&#x22;,
    value: &#x22;Present when the input is required.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to or away from the input.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;Removes the previous character, intelligently handling mask characters.&#x22;,
  },
  {
    keys: [&#x22;Delete&#x22;],
    description: &#x22;Removes the next character.&#x22;,
  },
  {
    keys: [&#x22;Ctrl + V&#x22;, &#x22;Cmd + V&#x22;],
    description: &#x22;Pastes content with intelligent mask formatting.&#x22;,
  },
  {
    keys: [&#x22;Ctrl + A&#x22;, &#x22;Cmd + A&#x22;],
    description: &#x22;Selects all input content.&#x22;,
  },
]"
/>


# Masonry
URL: /docs/components/base/masonry



<ComponentTabs name="masonry-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="masonry" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Masonry,
  MasonryItem,
} from "@/components/ui/masonry";

return (
  <Masonry>
    <MasonryItem />
  </Masonry>
)
```

## Examples [#examples]

### Linear Layout [#linear-layout]

Set `linear` to `true` to maintain item order from left to right.

<ComponentTabs name="masonry-linear-demo" />

### Server Side Rendering [#server-side-rendering]

Use `defaultWidth` and `defaultHeight`, and item `fallback` to render items on the server. This is useful for preventing layout shift and hydration errors.

<ComponentTabs name="masonry-ssr-demo" />

## API Reference [#api-reference]

### Masonry [#masonry]

The main container component for the masonry layout.

<AutoTypeTable path="./types/base/masonry.ts" name="MasonryProps" />

### MasonryItem [#masonryitem]

Individual item component within the masonry layout.

<AutoTypeTable path="./types/base/masonry.ts" name="MasonryItemProps" />


# Media Player
URL: /docs/components/base/media-player



<ComponentTabs name="media-player-demo" />

## Installation [#installation]

> **Prerequisites:** Before installing the media player component, you'll need to update your existing shadcn/ui components to support portal containers.

<Steps>
  <Step>
    **DropdownMenu**

    ```diff
    function DropdownMenuContent({
      align = "start",
      alignOffset = 0,
      side = "bottom",
      sideOffset = 4,
      className,
    + container,
      ...props
    }: MenuPrimitive.Popup.Props &
      Pick<
        MenuPrimitive.Positioner.Props,
        "align" | "alignOffset" | "side" | "sideOffset"
    - >) {
    + > & {
    +   container?: MenuPrimitive.Portal.Props["container"];
    + }) {
      return (
    -    <MenuPrimitive.Portal>
    +    <MenuPrimitive.Portal container={container}>
    ```
  </Step>

  <Step>
    **Tooltip**

    ```diff
    function TooltipContent({
      className,
      side = "top",
      sideOffset = 4,
      align = "center",
      alignOffset = 0,
    + container,
      children,
      ...props
    }: TooltipPrimitive.Popup.Props &
      Pick<
        TooltipPrimitive.Positioner.Props,
        "align" | "alignOffset" | "side" | "sideOffset"
    - >) {
    + > & {
    +   container?: TooltipPrimitive.Portal.Props["container"];
    + }) {
      return (
    -    <TooltipPrimitive.Portal>
    +    <TooltipPrimitive.Portal container={container}>
    ```
  </Step>
</Steps>

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <Steps>
      <Step>
        After completing the prerequisite component updates, install the media player:

        <CodeBlockTabs defaultValue="npm" groupId="package-manager">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Step>
    </Steps>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        After completing the prerequisite component updates, install the required dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils media-chrome
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils media-chrome
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils media-chrome
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils media-chrome
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="media-player" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  MediaPlayer,
  MediaPlayerVideo,
  MediaPlayerAudio,
  MediaPlayerLoading,
  MediaPlayerError,
  MediaPlayerVolumeIndicator,
  MediaPlayerControls,
  MediaPlayerControlsOverlay,
  MediaPlayerPlay,
  MediaPlayerSeekBackward,
  MediaPlayerSeekForward,
  MediaPlayerVolume,
  MediaPlayerSeek,
  MediaPlayerTime,
  MediaPlayerPlaybackSpeed,
  MediaPlayerLoop,
  MediaPlayerCaptions,
  MediaPlayerFullscreen,
  MediaPlayerDownload,
  MediaPlayerSettings,
} from "@/components/ui/media-player";

return (
  <MediaPlayer>
    <MediaPlayerVideo>
      <source src="..." type="video/mp4" />
    </MediaPlayerVideo>
    <MediaPlayerLoading />
    <MediaPlayerError />
    <MediaPlayerVolumeIndicator />
    <MediaPlayerControls>
      <MediaPlayerControlsOverlay />
      <MediaPlayerPlay />
      <MediaPlayerSeekBackward />
      <MediaPlayerSeekForward />
      <MediaPlayerVolume />
      <MediaPlayerSeek />
      <MediaPlayerTime />
      <MediaPlayerPlaybackSpeed />
      <MediaPlayerLoop />
      <MediaPlayerCaptions />
      <MediaPlayer.PiP />
      <MediaPlayer.Fullscreen />
      <MediaPlayer.Download />
    </MediaPlayer.Controls>
  </MediaPlayer.Root>
)
```

## Examples [#examples]

### Audio Player [#audio-player]

Use the `Audio` component instead of `Video` for audio playback.

<ComponentTabs name="media-player-audio-demo" />

### With Settings Menu [#with-settings-menu]

Media player with a settings menu with playback speed, caption option, and resolution selector.

<ComponentTabs name="media-player-settings-demo" />

### HLS Playback [#hls-playback]

Media player with HLS (HTTP Live Streaming) support for adaptive bitrate streaming.

This example demonstrates using the [Mux Video React](https://github.com/muxinc/elements/tree/main/packages/mux-video-react) package as the video element to enable HLS playback.

<ComponentTabs name="media-player-hls-demo" />

### With Error Handling [#with-error-handling]

Media player with custom error handling and retry functionality.

<ComponentTabs name="media-player-error-demo" />

### With Playlist [#with-playlist]

A media player example that includes a playlist, similar to music streaming applications.

<ComponentTabs name="media-player-playlist-demo" />

## API Reference [#api-reference]

### MediaPlayer [#mediaplayer]

The main container component for the media player.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-controls-visible]&#x22;,
    value: &#x22;Present when the controls are visible.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the media player is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
]"
/>

### MediaPlayerVideo [#mediaplayervideo]

The video element, integrated with the player state.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerVideoProps" />

### MediaPlayerAudio [#mediaplayeraudio]

The audio element, integrated with the player state.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerAudioProps" />

### MediaPlayerControls [#mediaplayercontrols]

A container for the media player controls.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerControlsProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the controls are disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
  {
    title: &#x22;[data-visible]&#x22;,
    value: &#x22;Present when the controls are visible.&#x22;,
  },
]"
/>

### MediaPlayerControlsOverlay [#mediaplayercontrolsoverlay]

Displays as a subtle backdrop that improves readability for media controls.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerControlsOverlayProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
  {
    title: &#x22;[data-visible]&#x22;,
    value: &#x22;Present when the controls are visible.&#x22;,
  },
]"
/>

### MediaPlayerLoading [#mediaplayerloading]

A loading indicator that appears when media is loading, similar to YouTube/Netflix style.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerLoadingProps" />

### MediaPlayerError [#mediaplayererror]

An error component that displays when media playback encounters an error, with retry and reload options.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerErrorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
]"
/>

### MediaPlayerVolumeIndicator [#mediaplayervolumeindicator]

A volume indicator that appears when the volume is changed with keyboard interactions.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerVolumeIndicatorProps" />

### MediaPlayerPlay [#mediaplayerplay]

A button to play or pause the media.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerPlayProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerSeekBackward [#mediaplayerseekbackward]

A button to seek backward in the media.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerSeekBackwardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

### MediaPlayerSeekForward [#mediaplayerseekforward]

A button to seek forward in the media.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerSeekForwardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

### MediaPlayerSeek [#mediaplayerseek]

A slider component to seek through the media playback.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerSeekProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the slider is disabled.&#x22;,
  },
  {
    title: &#x22;[data-hovering]&#x22;,
    value: &#x22;Present when the seek slider is being actively hovered.&#x22;,
  },
  {
    title: &#x22;[data-slider='']&#x22;,
    value: &#x22;Present on the seek slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-container']&#x22;,
    value: &#x22;The container for the seek slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek']&#x22;,
    value: &#x22;The root for the seek slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-buffered']&#x22;,
    value: &#x22;The buffered progress indicator within the track.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-hover-range']&#x22;,
    value: &#x22;The hover preview range indicator.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-chapter-separator']&#x22;,
    value: &#x22;Chapter separators displayed on the track.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-thumbnail']&#x22;,
    value: &#x22;The thumbnail preview container in the tooltip.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-chapter-title']&#x22;,
    value: &#x22;The chapter title in the tooltip.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-time']&#x22;,
    value: &#x22;The time display in the tooltip.&#x22;,
  },
]"
/>

#### Styling [#styling]

```tsx
<MediaPlayer.Seek 
  className={
    cn(
      "**:data-[slot='media-player-seek-buffered']:bg-primary/60",
      "**:data-[slot='media-player-seek-hover-range']:bg-primary/70",
      "**:data-[slot='media-player-seek-chapter-separator']:w-1 **:data-[slot='media-player-seek-chapter-separator']:bg-muted",
      "**:data-[slot='media-player-seek-thumbnail']:border-2 **:data-[slot='media-player-seek-thumbnail']:border-ring"
    )
  }
/>
```

### MediaPlayerVolume [#mediaplayervolume]

A slider component to control the media volume.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerVolumeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the volume control is disabled.&#x22;,
  },
  {
    title: &#x22;[data-slider='']&#x22;,
    value: &#x22;Present on the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-volume-container']&#x22;,
    value: &#x22;The container for the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-volume-trigger']&#x22;,
    value: &#x22;The trigger for the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-volume']&#x22;,
    value: &#x22;The root for the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerTime [#mediaplayertime]

Displays the current time, duration, or remaining time of the media.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerTimeProps" />

### MediaPlayerPlaybackSpeed [#mediaplayerplaybackspeed]

A select dropdown to control the media playback speed.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerPlaybackSpeedProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the select is disabled.&#x22;,
  },
]"
/>

### MediaPlayerLoop [#mediaplayerloop]

A button to toggle loop mode.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerLoopProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },   
]"
/>

### MediaPlayerFullscreen [#mediaplayerfullscreen]

A button to toggle fullscreen mode.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerFullscreenProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerPiP [#mediaplayerpip]

A button to toggle picture in picture mode (video only).

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerPiPProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerCaptions [#mediaplayercaptions]

A button to toggle captions or subtitles (video only).

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerCaptionsProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerDownload [#mediaplayerdownload]

A button to download the media file.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerDownloadProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

### MediaPlayerSettings [#mediaplayersettings]

A dropdown menu with playback speed selector, caption selector, and resolution selector.

<AutoTypeTable path="./types/base/media-player.ts" name="MediaPlayerSettingsProps" />

**Features:**

* Playback speed control with customizable speeds
* Video quality/resolution selection (when available)
* Captions/subtitles control
* Organized in a clean dropdown interface

```tsx
<MediaPlayer.Settings 
  speeds={[0.5, 0.75, 1, 1.25, 1.5, 2]}
/>
```

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;, &#x22;K&#x22;],
    description: &#x22;Toggles play/pause.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Seeks forward 5 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Seeks backward 5 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;J&#x22;],
    description: &#x22;Seeks backward 10 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;L&#x22;],
    description: &#x22;Seeks forward 10 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowRight&#x22;],
    description: &#x22;Seeks forward 5 seconds (audio only).&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowLeft&#x22;],
    description: &#x22;Seeks backward 5 seconds (audio only).&#x22;,
  },
  {
    keys: [&#x22;0&#x22;, &#x22;1&#x22;, &#x22;2&#x22;, &#x22;3&#x22;, &#x22;4&#x22;, &#x22;5&#x22;, &#x22;6&#x22;, &#x22;7&#x22;, &#x22;8&#x22;, &#x22;9&#x22;],
    description: &#x22;Seeks to 0%-90% of duration.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Seeks to beginning.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Seeks to end.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Increases volume (video only).&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Decreases volume (video only).&#x22;,
  },
  {
    keys: [&#x22;M&#x22;],
    description: &#x22;Toggles mute.&#x22;,
  },
  {
    keys: [&#x22;R&#x22;],
    description: &#x22;Toggles repeat mode.&#x22;,
  },
  {
    keys: [&#x22;F&#x22;],
    description: &#x22;Toggles fullscreen.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Exits fullscreen when in fullscreen mode.&#x22;,
  },
  {
    keys: [&#x22;>&#x22;],
    description: &#x22;Increases playback speed.&#x22;,
  },
  {
    keys: [&#x22;<&#x22;],
    description: &#x22;Decreases playback speed.&#x22;,
  },
  {
    keys: [&#x22;C&#x22;],
    description: &#x22;Toggles captions (video only, if available).&#x22;,
  },
  {
    keys: [&#x22;P&#x22;],
    description: &#x22;Toggles Picture-in-Picture.&#x22;,
  },
  {
    keys: [&#x22;D&#x22;],
    description: &#x22;Downloads the media file (if download button is present).&#x22;,
  },
]"
/>

## Credits [#credits]

* [FASSounds](https://pixabay.com/users/fassounds-3433550/?utm_source=link-attribution\&utm_medium=referral\&utm_campaign=music\&utm_content=160166) - For the audio file used in basic examples.
* [Pika](https://pika.art) - For the video file used in basic examples.
* [Elephants Dream](https://orange.blender.org/) - Open movie by the Blender Foundation, used in settings demo under Creative Commons Attribution 2.5.
* [Mux](https://www.mux.com/) - For HLS video streaming and VTT files used in HLS and settings demos.
* [Media Chrome](https://www.media-chrome.org/) - For VTT chapter and caption files used in examples.
* [RandomMind](https://opengameart.org/users/randommind) - For "Medieval: Battle" track used in playlist demo, available under CC0 from OpenGameArt.org.
* [The Lemming Shepherds](https://www.dropbox.com/s/mvvwaw1msplnteq/City%20Lights%20-%20The%20Lemming%20Shepherds.mp3) - For "City Lights" track used in playlist demo.
* [Picsum](https://picsum.photos/) - For placeholder cover images used in playlist demo.


# Mention
URL: /docs/components/base/mention



<ComponentTabs name="mention-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/mention
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/mention
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/mention
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/mention
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/mention
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/mention
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/mention
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/mention
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="mention" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Mention,
  MentionLabel,
  MentionInput,
  MentionPortal,
  MentionContent,
  MentionItem,
} from "@diceui/mention";

return (
  <Mention>
    <MentionLabel />
    <MentionInput />
    <MentionPortal>
      <MentionContent>
        <MentionItem />
      </MentionContent>
    </MentionPortal>
  </Mention>
)
```

## Examples [#examples]

### Custom Trigger [#custom-trigger]

<ComponentTabs name="mention-custom-trigger-demo" />

### With Custom Filter [#with-custom-filter]

<ComponentTabs name="mention-custom-filter-demo" />

## API Reference [#api-reference]

### Mention [#mention]

The container for all mention parts. Mention tags can be styled using the `data-tag` attribute within the root.

<AutoTypeTable path="./types/base/mention.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### MentionLabel [#mentionlabel]

An accessible label that describes the mention input. Associates with the input element for screen readers.

<AutoTypeTable path="./types/base/mention.ts" name="LabelProps" />

### MentionInput [#mentioninput]

The text input field that users can type into to trigger mentions.

<AutoTypeTable path="./types/base/mention.ts" name="InputProps" />

### MentionPortal [#mentionportal]

A portal for rendering the mention content outside of its DOM hierarchy.

<AutoTypeTable path="./types/base/mention.ts" name="PortalProps" />

### MentionContent [#mentioncontent]

The popover container for mention items. Positions the mention popover relative to the cursor position.

<AutoTypeTable path="./types/base/mention.ts" name="ContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--dice-transform-origin&#x22;,
    description: &#x22;Transform origin for cursor positioning.&#x22;,
  },
  {
    title: &#x22;--dice-available-width&#x22;,
    description: &#x22;Available width in the viewport for the popover element.&#x22;,
  },
  {
    title: &#x22;--dice-available-height&#x22;,
    description: &#x22;Available height in the viewport for the popover element.&#x22;,
  },
]"
/>

### MentionItem [#mentionitem]

An interactive option in the mention list.

<AutoTypeTable path="./types/base/mention.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the item is highlighted.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The value of the item.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When open, selects the highlighted mention option.&#x22;
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;When open, highlights the previous mention option.&#x22;
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;When open, highlights the next mention option.&#x22;
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;When open, highlights the first mention option.&#x22;
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;When open, highlights the last mention option.&#x22;
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the mention popover and returns focus to the input.&#x22;
  },
]"
/>


# Phone Input
URL: /docs/components/base/phone-input



<ComponentTabs name="phone-input-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your project.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="phone-input" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  PhoneInput,
  PhoneInputCountrySelect,
  PhoneInputField,
} from "@/components/ui/phone-input";

return (
  <PhoneInput>
    <PhoneInputCountrySelect />
    <PhoneInputField />
  </PhoneInput>
)
```

## Examples [#examples]

### Custom Countries [#custom-countries]

Provide a custom list of countries to display in the dropdown.

<ComponentTabs name="phone-input-custom-countries-demo" />

### With Form [#with-form]

Use the phone input component in a form with validation.

<ComponentTabs name="phone-input-form-demo" />

## API Reference [#api-reference]

### PhoneInput [#phoneinput]

The root container component that acts as both the wrapper and input group. Handles layout, borders, and focus states.

<AutoTypeTable path="./types/base/phone-input.ts" name="PhoneInputProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the phone input is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the phone input is invalid&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the phone input is read-only&#x22;,
  },
]"
/>

### PhoneInputCountrySelect [#phoneinputcountryselect]

The button component that triggers the country dropdown. Uses Popover and Command internally for the country list.

<AutoTypeTable path="./types/base/phone-input.ts" name="PhoneInputCountrySelectProps" />

### PhoneInputField [#phoneinputfield]

The input field component for entering the phone number.

<AutoTypeTable path="./types/base/phone-input.ts" name="PhoneInputFieldProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description:
      &#x22;Moves focus to the next focusable element (country select or phone input field).&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;, &#x22;Enter&#x22;],
    description: &#x22;Opens the country dropdown when focused on the country select button.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the country dropdown.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowDown&#x22;],
    description:
      &#x22;Navigate through country items when the dropdown is open.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;, &#x22;End&#x22;],
    description:
      &#x22;Jump to first or last country in the list.&#x22;,
  },
  {
    keys: [&#x22;Type to search&#x22;],
    description:
      &#x22;Filter countries by name, dial code, or country code as you type.&#x22;,
  },
]"
/>


# Presentation
URL: /docs/components/base/presentation



<ComponentTabs name="presentation-demo" className="h-100 p-0" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/pptx
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/pptx
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/pptx
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/pptx
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hook into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-mobile" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="presentation" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

`@diceui/pptx` pulls in `@diceui/pptx-core` automatically. The thumbnail rail collapses below 768px behind a toggle, which is why this item also depends on `button` and `use-mobile`.

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Presentation,
  PresentationContent,
  PresentationError,
  PresentationLoading,
  PresentationSelection,
  PresentationSlide,
  PresentationThumbnailList,
  PresentationViewport,
} from "@/components/ui/presentation";

return (
  <Presentation>
    <PresentationThumbnailList />
    <PresentationContent>
      <PresentationLoading />
      <PresentationError />
      <PresentationViewport>
        <PresentationSlide>
          <PresentationSelection />
        </PresentationSlide>
      </PresentationViewport>
    </PresentationContent>
  </Presentation>
)
```

Pass a `File`, `Blob`, `ArrayBuffer`, or `Uint8Array` to `file` on `Presentation`. There is no toolbar in this item — toolbars are assembled around the primitives.

## Examples [#examples]

### Editing [#editing]

Load with `readOnly={false}` and place `PresentationSelection` inside `PresentationSlide` to move, resize, and edit text. Undo and redo shortcuts are opt-in via `undoRedoShortcuts`. Drag thumbnails to reorder slides.

This example also uses `PresentationZoomSelect`, a companion control built with `useZoom` and `select`. Install it with `@diceui/presentation-zoom-select`.

<ComponentTabs name="presentation-editing-demo" className="h-100 p-0" />

## API Reference [#api-reference]

### PresentationProvider [#presentationprovider]

Makes an existing store available to descendants without rendering any DOM. Use it when a toolbar has to sit outside `Presentation`, or when the store is created with `useCreatePresentationStore` before the tree mounts.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationProviderProps" />

### Presentation [#presentation]

The outermost component. Creates an internal store (or inherits one from `PresentationProvider`), loads the file, and provides context to all descendants.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationProps" />

### PresentationContent [#presentationcontent]

Layout wrapper for the viewport column next to the thumbnail rail.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationContentProps" />

### PresentationViewport [#presentationviewport]

Scrollable container that centers the slide and optionally auto-fits it to fill the available space. The styled wrapper defaults `autoFit` to `true` with 10px padding.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationViewportProps" />

### PresentationSlide [#presentationslide]

Renders the active slide as a scaled DOM tree. Mounts an empty wrapper immediately so sibling layout is stable. Children are placed in an overlay; put `PresentationSelection` here.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationSlideProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;idle&#x22;, &#x22;loading&#x22;, &#x22;ready&#x22;, &#x22;error&#x22;],
  },
]"
/>

### PresentationSelection [#presentationselection]

PowerPoint-style editing overlay. Enables drag-to-move, resize, inline text editing, multi-select, and keyboard shortcuts. Renders nothing unless the presentation was loaded with `readOnly={false}`.

Must be placed inside `PresentationSlide`.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationSelectionProps" />

<CSSVariablesTable
  data="[
  {
    title: &#x22;--presentation-selection&#x22;,
    description: &#x22;Accent color for the selection overlay, resize handles, and marquee.&#x22;,
    defaultValue: &#x22;var(--ring)&#x22;,
  },
]"
/>

### PresentationLoading [#presentationloading]

Renders its children only while the presentation is in the `"loading"` state.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationLoadingProps" />

### PresentationError [#presentationerror]

Renders its children only when the presentation fails to parse.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationErrorProps" />

### PresentationThumbnailList [#presentationthumbnaillist]

Scrollable list of slide thumbnails. Below 768px the rail collapses behind a toggle button and closes on outside pointerup or Escape.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationThumbnailListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-mobile]&#x22;,
    value: &#x22;Present when the viewport is below 768px.&#x22;,
  },
]"
/>

### PresentationThumbnailItem [#presentationthumbnailitem]

Clickable item for a single slide in a `PresentationThumbnailList`.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationThumbnailItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-active]&#x22;,
    value: &#x22;Present when this item's slide is the active slide.&#x22;,
  },
]"
/>

### PresentationThumbnailItemPreview [#presentationthumbnailitempreview]

Renders the slide miniature for the enclosing `PresentationThumbnailItem`. Previews are rendered lazily as they approach the viewport.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationThumbnailItemPreviewProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-pending]&#x22;,
    value: &#x22;Present while the miniature has not been rendered yet.&#x22;,
  },
]"
/>

### PresentationThumbnailItemNumber [#presentationthumbnailitemnumber]

Renders the 1-based slide number for the enclosing `PresentationThumbnailItem`.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationThumbnailItemNumberProps" />

### PresentationZoomSelect [#presentationzoomselect]

Companion select for Fit and explicit zoom levels. Must be used inside `PresentationProvider` or `Presentation`.

<AutoTypeTable path="./types/base/presentation.ts" name="PresentationZoomSelectProps" />

### usePresentation [#usepresentation]

Subscribes to top-level presentation state: parse status, progress, and errors.

<AutoTypeTable path="./types/base/presentation.ts" name="UsePresentationResult" />

### useSlide [#useslide]

Subscribes to slide navigation state and exposes navigation actions.

<AutoTypeTable path="./types/base/presentation.ts" name="UseSlideResult" />

### useZoom [#usezoom]

Subscribes to zoom state. Setting an explicit level turns auto-fit off; `setAutoFit(true)` turns it back on.

<AutoTypeTable path="./types/base/presentation.ts" name="UseZoomResult" />

### useHistory [#usehistory]

Undo, redo, and whether the deck has unsaved edits.

<AutoTypeTable path="./types/base/presentation.ts" name="UseHistoryResult" />

Create a store with `useCreatePresentationStore` for programmatic `load`, `edit`, `save`, and `reset`. See the [store API](https://pptx.diceui.com/docs/store) for the full imperative surface.

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

#### Thumbnail list [#thumbnail-list]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowDown&#x22;],
    description: &#x22;Moves focus and navigates to the previous or next slide.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves focus to the first slide.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves focus to the last slide.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the thumbnail rail on mobile.&#x22;,
  },
]"
/>

#### Selection overlay [#selection-overlay]

Available when the presentation is loaded with `readOnly={false}`.

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Arrow Keys&#x22;],
    description: &#x22;Nudges the selection by 1px. Hold Shift for 10px.&#x22;,
  },
  {
    keys: [&#x22;Delete&#x22;, &#x22;Backspace&#x22;],
    description: &#x22;Deletes the selected shapes.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Exits text editing, then deselects.&#x22;,
  },
  {
    keys: [&#x22;Ctrl/Cmd + A&#x22;],
    description: &#x22;Selects every shape on the slide.&#x22;,
  },
  {
    keys: [&#x22;Ctrl/Cmd + Z&#x22;],
    description: &#x22;Undo. Bound only when undoRedoShortcuts is true.&#x22;,
  },
  {
    keys: [&#x22;Ctrl/Cmd + Y&#x22;, &#x22;Ctrl/Cmd + Shift + Z&#x22;],
    description: &#x22;Redo. Bound only when undoRedoShortcuts is true.&#x22;,
  },
]"
/>


# QR Code
URL: /docs/components/base/qr-code



<ComponentTabs name="qr-code-demo" className="items-center justify-center" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils qrcode
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Install the type definitions:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @types/qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @types/qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @types/qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @types/qrcode
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="qr-code" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  QRCode,
  QRCodeCanvas,
  QRCodeSvg,
  QRCodeImage,
  QRCodeOverlay,
  QRCodeSkeleton,
  QRCodeDownload,
} from "@/components/ui/qr-code";

return (
  <QRCode>
    <QRCodeCanvas />
    <QRCodeSvg />
    <QRCodeImage />
    <QRCodeOverlay />
    <QRCodeSkeleton />
    <QRCodeDownload />
  </QRCode>
)
```

Swap `Canvas` with `Svg` or `Image` to render the qr code in svg and image formats respectively.

## Examples [#examples]

### Different Formats [#different-formats]

Render QR codes as Canvas, SVG, or Image elements.

<ComponentTabs name="qr-code-formats-demo" />

### Customization [#customization]

Customize colors, size, and error correction levels.

<ComponentTabs name="qr-code-customization-demo" />

### Overlay [#overlay]

Add logos, icons, or custom elements to the center of QR codes.

<ComponentTabs name="qr-code-overlay-demo" />

## API Reference [#api-reference]

### QRCode [#qrcode]

The main container component that provides context for QR code generation.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeProps" />

<CSSVariablesTable
  data="[
  {
    title: &#x22;--qr-code-size&#x22;,
    description: &#x22;The size of the QR code in pixels. Used to constrain child elements to the QR code dimensions.&#x22;,
    defaultValue: &#x22;Based on size prop (e.g., 200px)&#x22;,
  },
]"
/>

### Image [#image]

Renders the QR code as an HTML image element.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeImageProps" />

### Canvas [#canvas]

Renders the QR code using HTML5 Canvas.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeCanvasProps" />

### Svg [#svg]

Renders the QR code as an SVG element.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeSvgProps" />

### Overlay [#overlay-1]

Overlays content (like logos or icons) in the center of the QR code.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeOverlayProps" />

### Skeleton [#skeleton]

Displays a loading placeholder while the QR code is being generated. Automatically hides once the QR code is ready.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeSkeletonProps" />

### Download [#download]

A button component for downloading the QR code.

<AutoTypeTable path="./types/base/qr-code.ts" name="QRCodeDownloadProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Activates the download button when focused.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Activates the download button when focused.&#x22;,
  },
]"
/>

## Error Correction Levels [#error-correction-levels]

QR codes support different error correction levels that determine how much of the code can be damaged while still being readable:

* **L (Low)**: \~7% of data can be restored
* **M (Medium)**: \~15% of data can be restored (default)
* **Q (Quartile)**: \~25% of data can be restored
* **H (High)**: \~30% of data can be restored

Higher error correction levels result in denser QR codes but provide better resilience to damage or distortion.

## Usage Notes [#usage-notes]

* The component uses dynamic imports to avoid SSR issues with the QR code library
* Canvas rendering provides the best performance for static QR codes
* SVG rendering is ideal for scalable, print-ready QR codes
* The download functionality works in all modern browsers
* QR codes are generated client-side for privacy and performance
* Child elements are automatically constrained by the `--qr-code-size` CSS variable to prevent layout issues
* When using the Overlay component, set `level="H"` (High error correction) to ensure the QR code remains scannable with up to 30% coverage


# Rating
URL: /docs/components/base/rating



<ComponentTabs name="rating-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/rating"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/rating"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/rating"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/rating"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="rating" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import { Rating, RatingItem } from "@/components/ui/rating";

return (
  <Rating>
    <RatingItem />
  </Rating>
)
```

## Examples [#examples]

### Themes [#themes]

Customize the rating component with different colors and icons.

<ComponentTabs name="rating-themes-demo" />

### Controlled State [#controlled-state]

Control the rating value with state.

<ComponentTabs name="rating-controlled-demo" />

### With Form [#with-form]

Integrate the rating component with form validation.

<ComponentTabs name="rating-form-demo" />

## API Reference [#api-reference]

### Rating [#rating]

The main container component for the rating.

<AutoTypeTable path="./types/base/rating.ts" name="RatingProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when readonly&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### RatingItem [#ratingitem]

Individual rating item (star) component.

<AutoTypeTable path="./types/base/rating.ts" name="RatingItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when readonly&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;empty&#x22;, &#x22;partial&#x22;, &#x22;full&#x22;],
  },
  {
    title: &#x22;[data-hovered]&#x22;,
    value: &#x22;Present when hovered&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowLeft&#x22;, &#x22;ArrowRight&#x22;],
    description: &#x22;Navigate between rating items.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Move to the first rating item.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Move to the last rating item.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Activate the focused rating item (when activationMode is 'manual').&#x22;,
  },
]"
/>


# Relative Time Card
URL: /docs/components/base/relative-time-card



<ComponentTabs name="relative-time-card-demo" className="h-[450px]" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the hover card component into your project.
      </Step>

      <ComponentSource name="hover-card" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="relative-time-card" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Examples [#examples]

### With Multiple Timezones [#with-multiple-timezones]

<ComponentTabs name="relative-time-card-timezones-demo" />

### With Variants [#with-variants]

<ComponentTabs name="relative-time-card-variants-demo" />

## API Reference [#api-reference]

### RelativeTimeCard [#relativetimecard]

The main component that displays relative time with hover functionality.

<AutoTypeTable path="./types/base/relative-time-card.ts" name="RelativeTimeCardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-popup-open]&#x22;,
    description: &#x22;Present on the trigger when the hover card is open.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Opens/closes the relative time card.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Opens the relative time card if closed.&#x22;,
  },
]"
/>

## Credits [#credits]

* [John Phamous](https://x.com/JohnPhamous/status/1836091528911216803) - For the initial implementation.


# Responsive Dialog
URL: /docs/components/base/responsive-dialog



<ComponentTabs name="responsive-dialog-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/utils vaul
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/utils vaul
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/utils vaul
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/utils vaul
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-mobile" />

      <Step>
        Copy and paste the dialog and drawer components into your project.
      </Step>

      <ComponentSource name="dialog" />

      <ComponentSource name="drawer" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="responsive-dialog" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ResponsiveDialog,
  ResponsiveDialogContent,
  ResponsiveDialogDescription,
  ResponsiveDialogFooter,
  ResponsiveDialogHeader,
  ResponsiveDialogTitle,
  ResponsiveDialogTrigger,
} from "@/components/ui/responsive-dialog";

<ResponsiveDialog>
  <ResponsiveDialogTrigger />
  <ResponsiveDialogContent>
    <ResponsiveDialogHeader>
      <ResponsiveDialogTitle />
      <ResponsiveDialogDescription />
    </ResponsiveDialogHeader>
    <ResponsiveDialogFooter />
  </ResponsiveDialogContent>
</ResponsiveDialog>
```

## Examples [#examples]

### Confirmation Dialog [#confirmation-dialog]

Use the responsive dialog to confirm destructive actions like deleting items.

<ComponentTabs name="responsive-dialog-confirm-demo" />

### Variant Styling [#variant-styling]

Each component exposes a `data-variant` attribute that can be used to apply different styles based on whether the dialog or drawer is rendered.

```tsx
<ResponsiveDialogContent className="data-[variant=drawer]:pb-8 data-[variant=dialog]:max-w-md">
  {/* content */}
</ResponsiveDialogContent>

<ResponsiveDialogFooter className="data-[variant=drawer]:flex-col data-[variant=dialog]:flex-row">
  {/* buttons */}
</ResponsiveDialogFooter>
```

## API Reference [#api-reference]

### ResponsiveDialog [#responsivedialog]

The root component that manages the dialog/drawer state.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogProps" />

### ResponsiveDialogTrigger [#responsivedialogtrigger]

The button that opens the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogContent [#responsivedialogcontent]

The content container for the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogHeader [#responsivedialogheader]

The header section of the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogHeaderProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogFooter [#responsivedialogfooter]

The footer section of the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogFooterProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogTitle [#responsivedialogtitle]

The title of the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogTitleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogDescription [#responsivedialogdescription]

The description of the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogDescriptionProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogClose [#responsivedialogclose]

The close button for the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogCloseProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogOverlay [#responsivedialogoverlay]

The overlay behind the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogOverlayProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogPortal [#responsivedialogportal]

The portal container for the dialog/drawer.

<AutoTypeTable path="./types/base/responsive-dialog.ts" name="ResponsiveDialogPortalProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Opens/closes the dialog when focus is on the trigger.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Opens/closes the dialog when focus is on the trigger.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the dialog/drawer and moves focus to the trigger.&#x22;,
  },
]"
/>


# Scroll Spy
URL: /docs/components/base/scroll-spy



<ComponentTabs name="scroll-spy-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the direction utilities into your project.
      </Step>

      <ComponentSource name="direction" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="scroll-spy" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ScrollSpy,
  ScrollSpyNav,
  ScrollSpyLink,
  ScrollSpyViewport,
  ScrollSpySection,
} from "@/components/ui/scroll-spy";

return (
  <ScrollSpy>
    <ScrollSpyNav>
      <ScrollSpyLink />
    </ScrollSpyNav>
    <ScrollSpyViewport>
      <ScrollSpySection />
    </ScrollSpyViewport>
  </ScrollSpy>
)
```

## Examples [#examples]

### Vertical Orientation [#vertical-orientation]

Set `orientation="vertical"` for content with vertical navigation.

<ComponentTabs name="scroll-spy-vertical-demo" />

### Controlled State [#controlled-state]

Use the `value` and `onValueChange` props to control the active section externally.

<ComponentTabs name="scroll-spy-controlled-demo" />

### Sticky Layout [#sticky-layout]

For full-page scroll behavior, you can use a sticky positioned navigation sidebar that stays fixed while the content scrolls. This works with the default window scroll (no `scrollContainer` prop needed).

```tsx
<ScrollSpy offset={100}>
  <ScrollSpyNav className="sticky top-20 h-fit">
    <ScrollSpyLink value="introduction">Introduction</ScrollSpyLink>
    <ScrollSpyLink value="getting-started">Getting Started</ScrollSpyLink>
    <ScrollSpyLink value="usage">Usage</ScrollSpyLink>
    <ScrollSpyLink value="api-reference">API Reference</ScrollSpyLink>
  </ScrollSpyNav>

  <ScrollSpyViewport>
    <ScrollSpySection value="introduction">
      <h2>Introduction</h2>
      <p>Your content here...</p>
    </ScrollSpySection>
    
    <ScrollSpySection value="getting-started">
      <h2>Getting Started</h2>
      <p>Your content here...</p>
    </ScrollSpySection>
    
    {/* More content sections */}
  </ScrollSpyViewport>
</ScrollSpy>
```

The key is to apply `sticky top-[offset]` to the `ScrollSpyNav` to keep the navigation visible as the page scrolls.

## API Reference [#api-reference]

### ScrollSpy [#scrollspy]

The root component that manages scroll tracking and contains all ScrollSpy parts.

<AutoTypeTable path="./types/base/scroll-spy.ts" name="ScrollSpyProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### Nav [#nav]

The navigation container component.

<AutoTypeTable path="./types/base/scroll-spy.ts" name="ScrollSpyNavProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### Link [#link]

Navigation link that scrolls to a section.

<AutoTypeTable path="./types/base/scroll-spy.ts" name="ScrollSpyLinkProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
]"
/>

### Viewport [#viewport]

The viewport container component for sections.

<AutoTypeTable path="./types/base/scroll-spy.ts" name="ScrollSpyViewportProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### Section [#section]

Content section that gets tracked by the scroll spy.

<AutoTypeTable path="./types/base/scroll-spy.ts" name="ScrollSpySectionProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Shortcuts [#keyboard-shortcuts]

The ScrollSpy component follows standard link navigation patterns:

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Move focus between navigation items.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Activate the focused navigation item and scroll to the associated section.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Activate the focused navigation item and scroll to the associated section.&#x22;,
  },
]"
/>


# Scroller
URL: /docs/components/base/scroller



<ComponentTabs name="scroller-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="scroller" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import { Scroller } from "@/components/ui/scroller"

<Scroller>
   {/* Scrollable content */}
</Scroller>
```

## Examples [#examples]

### Horizontal Scroll [#horizontal-scroll]

Set the `orientation` to `horizontal` to enable horizontal scrolling.

<ComponentTabs name="scroller-horizontal-demo" />

### Hidden Scrollbar [#hidden-scrollbar]

Set the `hideScrollbar` to `true` to hide the scrollbar while maintaining scroll functionality.

<ComponentTabs name="scroller-hidden-demo" />

### Navigation Buttons [#navigation-buttons]

Set the `withNavigation` to `true` to enable navigation buttons.

<ComponentTabs name="scroller-navigation-demo" />

## API Reference [#api-reference]

### Scroller [#scroller]

The main scrollable container component.

<AutoTypeTable path="./types/base/scroller.ts" name="ScrollerProps" />


# Segmented Input
URL: /docs/components/base/segmented-input



<ComponentTabs name="segmented-input-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="segmented-input" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import * as SegmentedInput from "@/components/ui/segmented-input";

return (
  <SegmentedInput.Root>
    <SegmentedInput.Item />
  </SegmentedInput.Root>
)
```

## Examples [#examples]

### Form Input [#form-input]

Use segmented inputs for structured form data like phone numbers or addresses.

<ComponentTabs name="segmented-input-form-demo" />

### RGB Color Input [#rgb-color-input]

Create color input controls using segmented inputs for RGB values.

<ComponentTabs name="segmented-input-rgb-demo" />

### Vertical Layout [#vertical-layout]

Display segmented inputs in a vertical orientation.

<ComponentTabs name="segmented-input-vertical-demo" />

## API Reference [#api-reference]

### SegmentedInput [#segmentedinput]

The main segmented input container.

<AutoTypeTable path="./types/base/segmented-input.ts" name="SegmentedInputProps" />

### SegmentedInputItem [#segmentedinputitem]

Individual input items within the segmented input.

<AutoTypeTable path="./types/base/segmented-input.ts" name="SegmentedInputItemProps" />

## Accessibility [#accessibility]

The SegmentedInput component follows standard web accessibility practices. Users navigate between inputs using Tab and Shift+Tab keys, which is the expected behavior for form controls.

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next input in the segment.&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous input in the segment.&#x22;,
  },
]"
/>


# Selection Toolbar
URL: /docs/components/base/selection-toolbar



<ComponentTabs name="selection-toolbar-demo" align="start" className="p-8" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @floating-ui/react-dom @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @floating-ui/react-dom @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @floating-ui/react-dom @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @floating-ui/react-dom @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="selection-toolbar" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  SelectionToolbar,
  SelectionToolbarItem,
  SelectionToolbarSeparator,
} from "@/components/ui/selection-toolbar";

return (
  <SelectionToolbar>
    <SelectionToolbarItem />
    <SelectionToolbarSeparator />
  </SelectionToolbar>
)
```

## Examples [#examples]

### Selection Info [#selection-info]

Track selection information with the `onSelectionChange` callback to display word count, character count, and other metrics.

<ComponentTabs name="selection-toolbar-info-demo" align="start" className="p-8" />

## API Reference [#api-reference]

### SelectionToolbar [#selectiontoolbar]

The root component that manages the toolbar's visibility and positioning.

<AutoTypeTable path="./types/base/selection-toolbar.ts" name="SelectionToolbarProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--selection-toolbar-available-width&#x22;,
    description: &#x22;The available width in the viewport for the toolbar to fit within, accounting for collision boundaries.&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 1200px)&#x22;,
  },
  {
    title: &#x22;--selection-toolbar-available-height&#x22;,
    description: &#x22;The available height in the viewport for the toolbar to fit within, accounting for collision boundaries.&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 800px)&#x22;,
  },
  {
    title: &#x22;--selection-toolbar-anchor-width&#x22;,
    description: &#x22;The width of the selected text (anchor element).&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 150px)&#x22;,
  },
  {
    title: &#x22;--selection-toolbar-anchor-height&#x22;,
    description: &#x22;The height of the selected text (anchor element).&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 24px)&#x22;,
  },
]"
/>

### SelectionToolbarItem [#selectiontoolbaritem]

An actionable item within the toolbar, typically containing an icon.

<AutoTypeTable path="./types/base/selection-toolbar.ts" name="SelectionToolbarItemProps" />

### SelectionToolbarSeparator [#selectiontoolbarseparator]

A visual separator between toolbar items.

<AutoTypeTable path="./types/base/selection-toolbar.ts" name="SelectionToolbarSeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the toolbar and clears the text selection.&#x22;,
  },
]"
/>


# Sortable
URL: /docs/components/base/sortable



<ComponentTabs name="sortable-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/sortable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/sortable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/sortable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/sortable
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="sortable" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Sortable,
  SortableContent,
  SortableItem,
  SortableItemHandle,
  SortableOverlay,
} from "@/components/ui/sortable";

return (
  <Sortable>
    <SortableContent>
      <SortableItem>
        <SortableItemHandle />
      </SortableItem>
      <SortableItem />
    </SortableContent>
    <SortableOverlay />
  </Sortable>
)
```

Every part accepts a `render` prop, so an item can be composed with your own element or component instead of the default `div`.

```tsx
<SortableItem value={item.id} render={<Card />}>
  {item.name}
</SortableItem>
```

## Usage [#usage]

### With Primitive Values [#with-primitive-values]

When using primitive arrays (strings, numbers), the `getItemValue` prop is optional. The component will automatically use the item itself as the unique identifier.

```tsx
const [items, setItems] = React.useState(["Item 1", "Item 2", "Item 3"]);

<Sortable value={items} onValueChange={setItems}>
  <SortableContent>
    {items.map((item) => (
      <SortableItem key={item} value={item}>
        {item}
      </SortableItem>
    ))}
  </SortableContent>
</Sortable>
```

### With Object Arrays [#with-object-arrays]

When using object arrays, the `getItemValue` prop is required to extract a unique identifier from each item.

```tsx
const [items, setItems] = React.useState([
  { id: 1, name: "Item 1" },
  { id: 2, name: "Item 2" },
]);

<Sortable
  value={items}
  onValueChange={setItems}
  getItemValue={(item) => item.id}
>
  <SortableContent>
    {items.map((item) => (
      <SortableItem key={item.id} value={item.id}>
        {item.name}
      </SortableItem>
    ))}
  </SortableContent>
</Sortable>
```

## Examples [#examples]

### With Dynamic Overlay [#with-dynamic-overlay]

Display a dynamic overlay when an item is being dragged.

<ComponentTabs name="sortable-dynamic-overlay-demo" />

### With Handle [#with-handle]

Use `SortableItemHandle` as a drag handle for sortable items.

<ComponentTabs name="sortable-handle-demo" />

### With Primitive Values [#with-primitive-values-1]

Use an array of primitives (string or number) instead of objects for sorting.

<ComponentTabs name="sortable-primitive-values-demo" />

## API Reference [#api-reference]

### Sortable [#sortable]

The main container component for sortable functionality.

<AutoTypeTable path="./types/base/sortable.ts" name="SortableProps" />

### SortableContent [#sortablecontent]

Container for sortable items. Multiple `SortableContent` components can be used within a `Sortable` component.

<AutoTypeTable path="./types/base/sortable.ts" name="SortableContentProps" />

### SortableItem [#sortableitem]

Individual sortable item component.

<AutoTypeTable path="./types/base/sortable.ts" name="SortableItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the item is being dragged.&#x22;,
  },
]"
/>

### SortableItemHandle [#sortableitemhandle]

A button component that acts as a drag handle for sortable items.

<AutoTypeTable path="./types/base/sortable.ts" name="SortableItemHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the parent sortable item is being dragged.&#x22;,
  }
]"
/>

The component renders a `button` and adds the following styles:

* `select-none` for pointer events
* `cursor-grab` when not dragging (unless `flatCursor` is true)
* `cursor-grabbing` when dragging (unless `flatCursor` is true)
* `cursor-default` when `flatCursor` is true

### SortableOverlay [#sortableoverlay]

The overlay component that appears when an item is being dragged.

<AutoTypeTable path="./types/base/sortable.ts" name="SortableOverlayProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Picks up the sortable item for reordering when released, and drops the item in its new position when pressed again.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves the sortable item up in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves the sortable item down in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves the sortable item left in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves the sortable item right in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;Esc&#x22;],
    description: &#x22;Cancels the sort operation and returns the item to its original position.&#x22;,
  },
]"
/>


# Speed Dial
URL: /docs/components/base/speed-dial



<ComponentTabs name="speed-dial-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="speed-dial" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  SpeedDial,
  SpeedDialTrigger,
  SpeedDialContent,
  SpeedDialItem,
  SpeedDialLabel,
  SpeedDialAction,
} from "@/components/ui/speed-dial";

return (
  <SpeedDial>
    <SpeedDialTrigger />
    <SpeedDialContent>
      <SpeedDialItem>
        <SpeedDialLabel />
        <SpeedDialAction />
      </SpeedDialItem>
    </SpeedDialContent>
  </SpeedDial>
)
```

## Examples [#examples]

### With Labels [#with-labels]

Display visible labels next to each action button for better discoverability.

<ComponentTabs name="speed-dial-labels-demo" />

### Hover Mode [#hover-mode]

Set `activationMode="hover"` on the root component to open the speed dial when hovering over the trigger. The speed dial will automatically close when the mouse leaves. Use the `delay` prop to control how long to wait before the speed dial opens.

<ComponentTabs name="speed-dial-hover-demo" />

### Controlled State [#controlled-state]

Use the `open` and `onOpenChange` props to control the speed dial state programmatically.

<ComponentTabs name="speed-dial-controlled-demo" />

### Sides [#sides]

The speed dial can expand in different directions using the `side` prop.

<ComponentTabs name="speed-dial-side-demo" />

### Fixed Positioning [#fixed-positioning]

To position the speed dial at a fixed location in the viewport (e.g., bottom-right corner), apply positioning classes to the `SpeedDial` root component, not the trigger.

```tsx
<SpeedDial className="fixed right-4 bottom-4">
  <SpeedDialTrigger>
    <Plus />
  </SpeedDialTrigger>
  <SpeedDialContent>
    {/* actions */}
  </SpeedDialContent>
</SpeedDial>
```

<Callout type="warn">
  **Important:** Apply `fixed` positioning to the `SpeedDial` root, not the `SpeedDialTrigger`. This ensures the content stays aligned with the trigger.
</Callout>

**Why this matters:** The content uses `absolute` positioning relative to its parent. If you apply `fixed` to the trigger instead, the content won't be able to position itself correctly relative to the trigger.

```tsx
// ❌ Incorrect - content won't align properly
<SpeedDial>
  <SpeedDialTrigger className="fixed right-4 bottom-4">
    <Plus />
  </SpeedDialTrigger>
  <SpeedDialContent>
    {/* actions */}
  </SpeedDialContent>
</SpeedDial>

// ✅ Correct - content aligns with trigger
<SpeedDial className="fixed right-4 bottom-4">
  <SpeedDialTrigger>
    <Plus />
  </SpeedDialTrigger>
  <SpeedDialContent>
    {/* actions */}
  </SpeedDialContent>
</SpeedDial>
```

## API Reference [#api-reference]

### SpeedDial [#speeddial]

The main container component for the speed dial.

<AutoTypeTable path="./types/base/speed-dial.ts" name="SpeedDialProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the speed dial is disabled.&#x22;,
  },
]"
/>

### SpeedDialTrigger [#speeddialtrigger]

The button that toggles the speed dial open/closed state.

<AutoTypeTable path="./types/base/speed-dial.ts" name="SpeedDialTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### SpeedDialContent [#speeddialcontent]

The container for the action items that appears when the speed dial is open.

<AutoTypeTable path="./types/base/speed-dial.ts" name="SpeedDialContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--speed-dial-gap&#x22;,
    description: &#x22;Gap between action items. Defaults to 0.5rem.&#x22;,
  },
  {
    title: &#x22;--speed-dial-offset&#x22;,
    description: &#x22;Offset distance from the trigger. Defaults to 0.5rem.&#x22;,
  },
  {
    title: &#x22;--speed-dial-transform-origin&#x22;,
    description: &#x22;Transform origin for animations based on the side.&#x22;,
  },
]"
/>

### SpeedDialItem [#speeddialitem]

A wrapper for each action and its associated label.

<AutoTypeTable path="./types/base/speed-dial.ts" name="SpeedDialItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--speed-dial-animation-duration&#x22;,
    description: &#x22;Duration of the animation for item appearance. Defaults to 200ms.&#x22;,
  },
  {
    title: &#x22;--speed-dial-delay&#x22;,
    description: &#x22;Animation delay for staggered item appearance.&#x22;,
  },
  {
    title: &#x22;--speed-dial-transform-origin&#x22;,
    description: &#x22;Transform origin for item animations.&#x22;,
  },
]"
/>

### SpeedDialAction [#speeddialaction]

An interactive button within the speed dial that triggers an action.

<AutoTypeTable path="./types/base/speed-dial.ts" name="SpeedDialActionProps" />

### SpeedDialLabel [#speeddiallabel]

A text label that describes the associated action.

<AutoTypeTable path="./types/base/speed-dial.ts" name="SpeedDialLabelProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;When focus is on the trigger, toggles the speed dial open/closed.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the speed dial and returns focus to the trigger.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus between actions. Closes the speed dial when focus moves out.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous action. Closes the speed dial when focus moves out.&#x22;,
  },
]"
/>


# Stack
URL: /docs/components/base/stack



<ComponentTabs name="stack-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="stack" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import * as Stack from "@/components/ui/stack";

<Stack.Root>
  <Stack.Item />
</Stack.Root>
```

## Examples [#examples]

### Without Expansion [#without-expansion]

Disable the hover expansion effect for a static stack.

<ComponentTabs name="stack-no-expand-demo" />

### Different Sides [#different-sides]

Stack items from different sides using the `side` prop.

<ComponentTabs name="stack-side-demo" />

## API Reference [#api-reference]

### Stack.Root [#stackroot]

The main container component that manages layout and hover interactions.

<AutoTypeTable path="./types/base/stack.ts" name="StackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-expanded]&#x22;,
    value: [&#x22;true&#x22;, &#x22;false&#x22;],
  },
]"
/>

### Stack.Item [#stackitem]

Individual items within the stack. These are automatically positioned and animated.

<AutoTypeTable path="./types/base/stack.ts" name="StackItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-index]&#x22;,
    value: [&#x22;number&#x22;],
  },
  {
    title: &#x22;[data-front]&#x22;,
    value: [&#x22;true&#x22;, &#x22;false&#x22;],
  },
  {
    title: &#x22;[data-visible]&#x22;,
    value: [&#x22;true&#x22;, &#x22;false&#x22;],
  },
]"
/>

## Features [#features]

* **Hover Expansion**: Items expand on hover to reveal all stacked items
* **Customizable**: Control visible items, gap, offset, and scale factor
* **Smooth Animations**: Elegant CSS transitions for all interactions
* **Flexible Styling**: Works with any content and styling approach
* **Accessibility**: Proper data attributes and semantic HTML

## Usage Notes [#usage-notes]

* The stack uses absolute positioning for items, ensure the parent container has enough space
* Use the `visibleItems` prop to control how many items are visible in the collapsed state
* The `scaleFactor` prop determines how much each subsequent item shrinks (0.05 = 5% smaller)
* Set `expandOnHover={false}` to disable the expansion effect
* All items beyond `visibleItems` will have reduced opacity and be non-interactive when collapsed

## Credits [#credits]

* [Emil Kowalski](https://emilkowal.ski/) - For the [Sonner](https://github.com/emilkowalski/sonner) toast library.


# Stat
URL: /docs/components/base/stat



<ComponentTabs name="stat-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="stat" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Stat,
  StatLabel,
  StatValue,
  StatIndicator,
  StatTrend,
  StatDescription,
  StatSeparator,
} from "@/components/ui/stat";

return (
  <Stat>
    <StatLabel>Total Revenue</StatLabel>
    <StatIndicator variant="icon" color="success">
      <DollarSign />
    </StatIndicator>
    <StatValue>$45,231</StatValue>
    <StatTrend trend="up">
      <ArrowUp />
      +20.1% from last month
    </StatTrend>
    <StatSeparator />
    <StatDescription>
      Total revenue generated in the current billing period
    </StatDescription>
  </Stat>
);
```

## Examples [#examples]

### Variants [#variants]

Explore different indicator variants and color themes.

<ComponentTabs name="stat-variants-demo" />

### Layout Options [#layout-options]

Combine different stat components to create rich statistical displays.

<ComponentTabs name="stat-layout-demo" />

## API Reference [#api-reference]

### Stat [#stat]

The main container component that provides a card-style layout for displaying statistics.

<AutoTypeTable path="./types/base/stat.ts" name="StatProps" />

### StatLabel [#statlabel]

A label component for the statistic title or category.

<AutoTypeTable path="./types/base/stat.ts" name="StatLabelProps" />

### StatIndicator [#statindicator]

A visual indicator component that can display icons, badges, or action buttons with various color themes.

<AutoTypeTable path="./types/base/stat.ts" name="StatIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;default&#x22;, &#x22;icon&#x22;, &#x22;badge&#x22;, &#x22;action&#x22;],
  },
  {
    title: &#x22;[data-color]&#x22;,
    value: [&#x22;default&#x22;, &#x22;success&#x22;, &#x22;info&#x22;, &#x22;warning&#x22;, &#x22;error&#x22;],
  },
]"
/>

### StatValue [#statvalue]

Displays the primary statistic value with emphasized typography.

<AutoTypeTable path="./types/base/stat.ts" name="StatValueProps" />

### StatTrend [#stattrend]

Displays trend information with directional styling (up, down, or neutral).

<AutoTypeTable path="./types/base/stat.ts" name="StatTrendProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-trend]&#x22;,
    value: [&#x22;up&#x22;, &#x22;down&#x22;, &#x22;neutral&#x22;],
  },
]"
/>

### StatSeparator [#statseparator]

A horizontal separator for dividing content within the stat card.

<AutoTypeTable path="./types/base/stat.ts" name="StatSeparatorProps" />

### StatDescription [#statdescription]

Additional descriptive text for providing context about the stat.


# Status
URL: /docs/components/base/status



<ComponentTabs name="status-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="status" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Status,
  StatusIndicator,
  StatusLabel,
} from "@/components/ui/status";

return (
  <Status variant="success">
    <StatusIndicator />
    <StatusLabel>Online</StatusLabel>
  </Status>
);
```

## Examples [#examples]

### Variants [#variants]

Status supports five color variants to represent different states.

<ComponentTabs name="status-variants-demo" />

### Text Only [#text-only]

Use status without the indicator for a simpler appearance.

<ComponentTabs name="status-text-only-demo" />

### Service Status List [#service-status-list]

Display multiple status items in a list format, ideal for system health dashboards.

<ComponentTabs name="status-list-demo" />

## API Reference [#api-reference]

### Status [#status]

The main container component that provides the badge-style wrapper with color variants.

<AutoTypeTable path="./types/base/status.ts" name="StatusProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;default&#x22;, &#x22;success&#x22;, &#x22;error&#x22;, &#x22;warning&#x22;, &#x22;info&#x22;],
  },
]"
/>

### StatusIndicator [#statusindicator]

An animated pulse indicator for the status.

<AutoTypeTable path="./types/base/status.ts" name="StatusIndicatorProps" />

### StatusLabel [#statuslabel]

The text label for the status.

<AutoTypeTable path="./types/base/status.ts" name="StatusLabelProps" />

## Accessibility [#accessibility]

The Status component uses semantic HTML and follows best practices for accessibility:

* Uses `div` elements with proper ARIA attributes when needed
* Color is not the only means of conveying information—always include text labels
* Supports keyboard navigation when used with interactive elements via `asChild`

## Notes [#notes]

* The animated ping effect uses Tailwind's built-in `animate-ping` utility for smooth performance
* Colors automatically adapt to dark mode
* The indicator animation runs continuously to draw attention to live status changes
* Use the `asChild` prop to render Status as a link or button for interactive use cases


# Stepper
URL: /docs/components/base/stepper



<ComponentTabs name="stepper-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the direction utility into your project.
      </Step>

      <ComponentSource name="direction" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="stepper" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Stepper,
  StepperList,
  StepperItem,
  StepperTrigger,
  StepperIndicator,
  StepperTitle,
  StepperDescription,
  StepperSeparator,
  StepperContent,
  StepperPrev,
  StepperNext,
} from "@/components/ui/stepper";

return (
  <Stepper>
    <StepperList>
      <StepperItem>
        <StepperTrigger>
          <StepperIndicator />
          <StepperTitle />
          <StepperDescription />
        </StepperTrigger>
        <StepperSeparator />
      </StepperItem>
    </StepperList>
    <StepperContent />
    <StepperPrev /> 
    <StepperNext />
  </Stepper>
)
```

## Examples [#examples]

### Vertical Layout [#vertical-layout]

A stepper with vertical orientation for compact layouts.

<ComponentTabs name="stepper-vertical-demo" />

### With Validation [#with-validation]

Use the `onValidate` prop to validate the current step before moving to the next one.

<ComponentTabs name="stepper-validation-demo" />

### With Form [#with-form]

A stepper integrated with form validation, showing step-by-step form completion.

<ComponentTabs name="stepper-form-demo" />

## API Reference [#api-reference]

### Stepper [#stepper]

The main container component for the stepper.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### StepperList [#stepperlist]

The container for stepper items, typically an ordered list.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### StepperItem [#stepperitem]

A single step item in the stepper.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperTrigger [#steppertrigger]

The clickable trigger for each step, typically wrapping the indicator.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperIndicator [#stepperindicator]

The visual indicator showing the step number or completion status.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperSeparator [#stepperseparator]

The line connecting steps, showing progress between them.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperSeparatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperTitle [#steppertitle]

The title text for each step.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperTitleProps" />

### StepperDescription [#stepperdescription]

The description text for each step.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperDescriptionProps" />

### StepperContent [#steppercontent]

The content area that displays for the active step.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperContentProps" />

### StepperPrev [#stepperprev]

A navigation button that moves to the previous step. Automatically disabled on the first step and skips validation when navigating backwards.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperPrevProps" />

### StepperNext [#steppernext]

A navigation button that moves to the next step. Automatically disabled on the last step and respects validation rules when navigating forwards.

<AutoTypeTable path="./types/base/stepper.ts" name="StepperNextProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Activates the focused step when clickable is enabled.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves focus to the previous step trigger.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;, &#x22;ArrowDown&#x22;],
    description: &#x22;Moves focus to the next step trigger.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves focus to the first step trigger.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves focus to the last step trigger.&#x22;,
  },
]"
/>


# Swap
URL: /docs/components/base/swap



<ComponentTabs name="swap-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="swap" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import { Swap, SwapOn, SwapOff } from "@/components/ui/swap";

return (
  <Swap>
    <SwapOn />
    <SwapOff />
  </Swap>
)
```

## Examples [#examples]

### Animations [#animations]

The swap component supports 4 different animation types: fade, rotate, flip, and scale.

<ComponentTabs name="swap-animations-demo" />

## API Reference [#api-reference]

### Swap [#swap]

The main container component for swap functionality.

<AutoTypeTable path="./types/base/swap.ts" name="SwapProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
  {
    title: &#x22;[data-animation]&#x22;,
    value: [&#x22;fade&#x22;, &#x22;rotate&#x22;, &#x22;flip&#x22;, &#x22;scale&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the swap is disabled&#x22;,
  },
]"
/>

### SwapOn [#swapon]

The content shown when the swap is in the swapped state.

<AutoTypeTable path="./types/base/swap.ts" name="SwapOnProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### SwapOff [#swapoff]

The content shown when the swap is in the default state.

<AutoTypeTable path="./types/base/swap.ts" name="SwapOffProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Toggles the swap state when activation mode is 'click'.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Toggles the swap state when activation mode is 'click'.&#x22;,
  },
]"
/>


# Tags Input
URL: /docs/components/base/tags-input



<ComponentTabs name="tags-input-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/tags-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/tags-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/tags-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/tags-input
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/tags-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/tags-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/tags-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/tags-input
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="tags-input" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  TagsInput,
  TagsInputLabel,
  TagsInputItem,
  TagsInputItemText,
  TagsInputItemDelete,
  TagsInputInput,
  TagsInputClear,
} from "@diceui/tags-input";

return (
  <TagsInput>
    <TagsInputLabel/>
    <TagsInputItem >
      <TagsInputItemText />
      <TagsInputItemDelete />
    </TagsInputItem>
    <TagsInputInput />
    <TagsInputClear />
  </TagsInput>
)
```

## Examples [#examples]

### Editable [#editable]

<ComponentTabs name="tags-input-editable-demo" />

### With Validation [#with-validation]

Validate the input value before adding it to the list. Can be used to prevent duplicate tags.

<ComponentTabs name="tags-input-validation-demo" />

### With Sortable [#with-sortable]

`TagsInput` can be composed with [`Sortable`](/docs/components/base/sortable) to allow reordering of tags.

<ComponentTabs name="tags-input-sortable-demo" />

## API Reference [#api-reference]

### TagsInput [#tagsinput]

Container for the tags input.

<AutoTypeTable path="./types/base/tags-input.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when readOnly.&#x22;,
  },
]"
/>

### TagsInputLabel [#tagsinputlabel]

Label element for the tags input.

<AutoTypeTable path="./types/base/tags-input.ts" name="LabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### TagsInputInput [#tagsinputinput]

Text input for adding new tags.

<AutoTypeTable path="./types/base/tags-input.ts" name="InputProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

### TagsInputItem [#tagsinputitem]

Individual tag item.

<AutoTypeTable path="./types/base/tags-input.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when highlighted.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-editing]&#x22;,
    value: &#x22;Present when being edited.&#x22;,
  },
  {
    title: &#x22;[data-editable]&#x22;,
    value: &#x22;Present when the tags input is editable.&#x22;,
  },
]"
/>

### TagsInputItemText [#tagsinputitemtext]

Text content of a tag.

<AutoTypeTable path="./types/base/tags-input.ts" name="ItemTextProps" />

### TagsInputItemDelete [#tagsinputitemdelete]

Button to remove a tag.

<AutoTypeTable path="./types/base/tags-input.ts" name="ItemDeleteProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
]"
/>

### TagsInputClear [#tagsinputclear]

Button to clear all tags.

<AutoTypeTable path="./types/base/tags-input.ts" name="ClearProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;visible&#x22;, &#x22;invisible&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Delete&#x22;],
    description: &#x22;When a tag is highlighted, removes it and sets focus to the next tag.&#x22;
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;When a tag is highlighted, removes it and sets focus to the previous tag. If there is no previous tag, focus moves to the next tag or input.&#x22;
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Highlights the previous tag. When cursor is at start of input, moves focus to the last tag.&#x22;
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Highlights the next tag. When cursor is at start of input, moves focus to the first tag.&#x22;
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Highlights the first tag in the list.&#x22;
  },
  {
    keys: [&#x22;End&#x22;], 
    description: &#x22;Highlights the last tag in the list.&#x22;
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When input has text, adds a new tag. When a tag is highlighted and editable is enabled, enters edit mode.&#x22;
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Clears tag highlight and edit mode, resets cursor to start.&#x22;
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;When `addOnTab` is enabled and input has text, adds a new tag. Otherwise, blurs the input.&#x22;
  }
]"
/>


# Time Picker
URL: /docs/components/base/time-picker



<ComponentTabs name="time-picker-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your project.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="time-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  TimePicker,
  TimePickerLabel,
  TimePickerInputGroup,
  TimePickerInput,
  TimePickerSeparator,
  TimePickerTrigger,
  TimePickerContent,
  TimePickerHour,
  TimePickerMinute,
  TimePickerClear,
} from "@/components/ui/time-picker";

return (
  <TimePicker>
    <TimePickerLabel />
    <TimePickerInputGroup>
      <TimePickerInput segment="hour" />
      <TimePickerSeparator />
      <TimePickerInput segment="minute" />
      <TimePickerInput segment="period" />
      <TimePickerTrigger />
    </TimePickerInputGroup>
    <TimePickerContent>
      <TimePickerHour />
      <TimePickerMinute />
      <TimePickerClear />
    </TimePickerContent>
  </TimePicker>
)
```

## Examples [#examples]

### With Step [#with-step]

Use the `hourStep`, `minuteStep`, and `secondStep` props to set custom intervals for hour, minute, and second selection respectively.

<ComponentTabs name="time-picker-step-demo" />

### With Seconds [#with-seconds]

Include seconds in time selection.

<ComponentTabs name="time-picker-seconds-demo" />

### Custom Placeholders [#custom-placeholders]

Customize empty segment placeholders for different display formats.

<ComponentTabs name="time-picker-placeholder-demo" />

### Open on Focus [#open-on-focus]

Use the `openOnFocus` prop to open the content when the input is focused.

<ComponentTabs name="time-picker-open-on-focus-demo" />

### Input Group Click Action [#input-group-click-action]

Configure what happens when clicking on empty space in the input group. By default, it focuses the first input for inline editing, but you can set it to open the popover instead.

<ComponentTabs name="time-picker-input-group-click-action-demo" />

### Controlled State [#controlled-state]

Control the time picker value programmatically.

<ComponentTabs name="time-picker-controlled-demo" />

### With Form [#with-form]

Use the time picker in a form with validation.

<ComponentTabs name="time-picker-form-demo" />

## API Reference [#api-reference]

### TimePicker [#timepicker]

The main container component for time picker functionality.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the time picker is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the time picker is invalid&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the time picker is read-only&#x22;,
  },
]"
/>

### TimePickerLabel [#timepickerlabel]

The label component for the time picker field.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerLabelProps" />

### TimePickerInputGroup [#timepickerinputgroup]

The container for input segments that sets up CSS variables for dynamic segment widths.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerInputGroupProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the time picker is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the time picker is invalid&#x22;,
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--time-picker-hour-input-width&#x22;,
    description: &#x22;The width of the hour input segment, dynamically calculated based on the hour placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
  {
    title: &#x22;--time-picker-minute-input-width&#x22;,
    description: &#x22;The width of the minute input segment, dynamically calculated based on the minute placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
  {
    title: &#x22;--time-picker-second-input-width&#x22;,
    description: &#x22;The width of the second input segment, dynamically calculated based on the second placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
  {
    title: &#x22;--time-picker-period-input-width&#x22;,
    description: &#x22;The width of the period (AM/PM) input segment, dynamically calculated based on the period placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
]"
/>

Must use style prop to override the css variables of the input segment, because the width is dynamically calculated based on the placeholder length.

### TimePickerTrigger [#timepickertrigger]

Button to open the time picker content.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: &#x22;'open' | 'closed'&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the time picker is disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the time picker is read-only&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the time picker is invalid&#x22;,
  },
]"
/>

### TimePickerContent [#timepickercontent]

Container for the time selection interface.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: &#x22;'open' | 'closed'&#x22;,
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: &#x22;The side where the content is positioned&#x22;,
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: &#x22;The alignment of the content&#x22;,
  },
]"
/>

### TimePickerHour [#timepickerhour]

Component for selecting hours.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerHourProps" />

### TimePickerMinute [#timepickerminute]

Component for selecting minutes.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerMinuteProps" />

### TimePickerSecond [#timepickersecond]

Component for selecting seconds.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerSecondProps" />

### TimePickerPeriod [#timepickerperiod]

Component for selecting AM/PM in 12-hour format.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerPeriodProps" />

### TimePickerSeparator [#timepickerseparator]

Visual separator between time units.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerSeparatorProps" />

### TimePickerClear [#timepickerclear]

Button to clear the selected time.

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerClearProps" />

### TimePickerInput [#timepickerinput]

Inline editable input field for time segments (hour, minute, second, period).

<AutoTypeTable path="./types/base/time-picker.ts" name="TimePickerInputProps" />

<CSSVariablesTable
  data="[
  {
    title: &#x22;--time-picker-hour-input-width&#x22;,
    description: &#x22;Can be set directly on the hour segment input to override the width for that specific input.&#x22;,
  },
  {
    title: &#x22;--time-picker-minute-input-width&#x22;,
    description: &#x22;Can be set directly on the minute segment input to override the width for that specific input.&#x22;,
  },
  {
    title: &#x22;--time-picker-second-input-width&#x22;,
    description: &#x22;Can be set directly on the second segment input to override the width for that specific input.&#x22;,
  },
  {
    title: &#x22;--time-picker-period-input-width&#x22;,
    description: &#x22;Can be set directly on the period segment input to override the width for that specific input.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;0-9&#x22;],
    description: &#x22;Type digits to enter time values in input segments. Auto-pads single digits (1 → 01) and auto-advances to next segment after two digits or when first digit exceeds maximum&#x22;,
  },
  {
    keys: [&#x22;A&#x22;, &#x22;1&#x22;],
    description: &#x22;Sets period to AM when period input is focused&#x22;,
  },
  {
    keys: [&#x22;P&#x22;, &#x22;2&#x22;],
    description: &#x22;Sets period to PM when period input is focused&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;When the input is focused, moves to next segment (hour → minute → second → period). When the content is open, moves to next column with wrapping&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;When the input is focused, moves to previous segment. When the content is open, moves to previous column with wrapping&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;When the input is focused, moves to next segment. When the content is open, moves to next column with wrapping&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;When the input is focused, moves to previous segment. When the content is open, moves to previous column with wrapping&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;When the input is focused, increments value with wrapping, selection preserved. When the content is open, navigates to previous value in column&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;When the input is focused, decrements value with wrapping, selection preserved. When the content is open, navigates to next value in column&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When the input is focused, confirms and removes focus. When the content is open, selects highlighted value. When the trigger is focused, opens/closes the content&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;When the input is focused, cancels editing and restores previous value. When the content is open, closes without changing value&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;When the trigger is focused, opens/closes the content&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;, &#x22;Delete&#x22;],
    description: &#x22;Clears focused segment back to placeholder (--) when entire segment is selected&#x22;,
  },
]"
/>

## Notes [#notes]

### Behavior [#behavior]

* **Native HTML time input behavior**: Replicates the exact behavior of `<input type="time">` for maximum familiarity
  * Auto-pads single digits instantly (typing "1" shows "01")
  * Smart auto-advance after two digits or when digit exceeds maximum first digit
  * Partial time values supported (e.g., "10:--" instead of "10:00")
  * Selection preserved after actions for seamless typing
* **Inline editing**: All time segments are always visible and editable, no need to open the content
* **Content for convenience**: The clock icon trigger opens the content for easier selection with mouse/touch
* **Keyboard-first design**: Full keyboard navigation between segments using arrow keys or tab
* **Clear segments**: Press Backspace or Delete on a selected segment to clear it back to "--"

### Format & Locale [#format--locale]

* **Automatic format detection**: Display format (12-hour vs 24-hour) is automatically detected from user's locale settings
* **Consistent value format**: The time value is always stored in 24-hour format ("HH:mm" or "HH:mm:ss"), regardless of display format
* **Locale override**: Use the `locale` prop to explicitly set a locale (e.g., "en-US" for 12-hour, "en-GB" for 24-hour)
* **Period shortcuts**: In 12-hour format, use A/P or 1/2 keys to quickly set AM/PM


# Timeline
URL: /docs/components/base/timeline



<ComponentTabs name="timeline-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the 

        `Direction`

         component into your project.
      </Step>

      <ComponentSource name="direction" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="timeline" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import {
  Timeline,
  TimelineItem,
  TimelineDot,
  TimelineConnector,
  TimelineContent,
  TimelineHeader,
  TimelineTitle,
  TimelineTime,
  TimelineDescription,
} from "@/components/ui/timeline";

<Timeline>
  <TimelineItem>
    <TimelineDot />
    <TimelineConnector />
    <TimelineContent>
      <TimelineHeader>
        <TimelineTitle />
        <TimelineTime />
      </TimelineHeader>
      <TimelineDescription />
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

## Examples [#examples]

### Horizontal Timeline [#horizontal-timeline]

Display timeline events horizontally across the screen.

<ComponentTabs name="timeline-horizontal-demo" />

### RTL Timeline [#rtl-timeline]

Display timeline with right-to-left layout for RTL languages.

<ComponentTabs name="timeline-rtl-demo" />

### Alternate Timeline [#alternate-timeline]

Display timeline events in an alternating pattern with content on both sides.

<ComponentTabs name="timeline-alternate-demo" />

### Horizontal Alternate Timeline [#horizontal-alternate-timeline]

Display timeline events horizontally with content alternating above and below.

<ComponentTabs name="timeline-horizontal-alternate-demo" />

### With Custom Dots [#with-custom-dots]

Add custom icons or content to the timeline dots using CSS variables.

<ComponentTabs name="timeline-custom-dot-demo" />

## API Reference [#api-reference]

### Timeline [#timeline]

The root container for timeline items.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;default&#x22;, &#x22;alternate&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--timeline-dot-size&#x22;,
    description: &#x22;The size (width and height) of the timeline dot marker.&#x22;,
    defaultValue: &#x22;0.875rem (14px)&#x22;,
  },
  {
    title: &#x22;--timeline-connector-thickness&#x22;,
    description: &#x22;The thickness of the timeline connector line.&#x22;,
    defaultValue: &#x22;0.125rem (2px)&#x22;,
  },
]"
/>

### TimelineItem [#timelineitem]

A single timeline item containing content, marker, and connector.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
  {
    title: &#x22;[data-alternate-right]&#x22;,
    value: [&#x22;Present when item is on the right/bottom in alternate variant&#x22;],
  },
]"
/>

### TimelineDot [#timelinedot]

The visual marker/dot for a timeline item.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineDotProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--timeline-dot-size&#x22;,
    description: &#x22;The size (width and height) of the timeline dot marker.&#x22;,
    defaultValue: &#x22;0.875rem (14px)&#x22;,
  },
]"
/>

### TimelineConnector [#timelineconnector]

The line connecting timeline items.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineConnectorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-completed]&#x22;,
    value: [&#x22;Present when connector represents a completed transition&#x22;],
  },
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--timeline-connector-thickness&#x22;,
    description: &#x22;The thickness of the timeline connector line.&#x22;,
    defaultValue: &#x22;0.125rem (2px)&#x22;,
  },
]"
/>

### TimelineHeader [#timelineheader]

Container for the title and time of a timeline item.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineHeaderProps" />

### TimelineTitle [#timelinetitle]

The title/heading of a timeline item.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineTitleProps" />

### TimelineDescription [#timelinedescription]

The description/body text of a timeline item.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineDescriptionProps" />

### TimelineContent [#timelinecontent]

Container for the timeline item's content (header, description, etc.).

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
]"
/>

### TimelineTime [#timelinetime]

A semantic time element for displaying dates/times.

<AutoTypeTable path="./types/base/timeline.ts" name="TimelineTimeProps" />

## Features [#features]

### Flexible Orientations [#flexible-orientations]

The timeline supports both vertical and horizontal orientations. Use the `orientation` prop on the root `Timeline` component to switch between layouts.

### Alternate Variant [#alternate-variant]

The timeline supports an alternate variant where content alternates on both sides of the timeline. Use the `variant="alternate"` prop on the root `Timeline` component to enable this layout. This works with both vertical and horizontal orientations:

* **Vertical alternate**: Content alternates left and right of the center line
* **Horizontal alternate**: Content alternates above and below the center line

```tsx
<Timeline variant="alternate" orientation="horizontal">
  {/* Content alternates above and below */}
</Timeline>
```

### RTL Support [#rtl-support]

The timeline fully supports right-to-left (RTL) layouts through the `dir` prop. When set to `"rtl"`, the timeline automatically flips its layout direction, making it ideal for RTL languages like Arabic, Hebrew, and Persian.

### Active Index [#active-index]

Control the visual state of timeline items using the `activeIndex` prop on the root component. Items before the active index will be marked as "completed", the item at the active index will be "active", and items after will be "pending".

```tsx
<Timeline activeIndex={2}>
  <TimelineItem>Step 1 - Completed</TimelineItem>
  <TimelineItem>Step 2 - Completed</TimelineItem>
  <TimelineItem>Step 3 - Active (index 2)</TimelineItem>
  <TimelineItem>Step 4 - Pending</TimelineItem>
</Timeline>
```

The `activeIndex` is zero-based, so `activeIndex={2}` makes the third item active.

### Custom Icons [#custom-icons]

Replace the default dot marker with custom icons or React components by passing children to `TimelineDot`, giving you full control over the visual appearance.

### Composition Pattern [#composition-pattern]

Built with Base UI's `useRender` hook for flexible composition. All components accept a `render` prop for custom rendering, giving you complete control over the structure and styling of your timeline.

## Accessibility [#accessibility]

### ARIA Roles [#aria-roles]

The timeline uses ARIA roles and attributes for proper accessibility:

* Root uses `role="list"` and `aria-orientation` to represent an ordered list of events
* Each item uses `role="listitem"` for proper list semantics
* Active items use `aria-current="step"` to indicate current position in the timeline
* Semantic `<time>` elements with `dateTime` attribute for proper date representation
* Connectors are marked with `aria-hidden="true"` as they're purely decorative


# Tour
URL: /docs/components/base/tour



<ComponentTabs name="tour-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react @base-ui/utils @floating-ui/react-dom
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react @base-ui/utils @floating-ui/react-dom
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react @base-ui/utils @floating-ui/react-dom
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react @base-ui/utils @floating-ui/react-dom
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="tour" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Tour,
  TourPortal,
  TourSpotlight,
  TourSpotlightRing,
  TourStep,
  TourArrow,
  TourClose,
  TourHeader,
  TourTitle,
  TourDescription,
  TourFooter,
  TourStepCounter,
  TourPrev,
  TourNext,
  TourSkip,
} from "@/components/ui/tour";

return (
  <Tour>
    <TourPortal>
      <TourSpotlight />
      <TourSpotlightRing />
      <TourStep>
        <TourArrow />
        <TourClose />
        <TourHeader>
          <TourTitle />
          <TourDescription />
        </TourHeader>
        <TourFooter>
          <TourStepCounter />
          <TourPrev />
          <TourNext />
          <TourSkip />
        </TourFooter>
      </TourStep>
    </TourPortal>
  </Tour>
)
```

## Examples [#examples]

### Controlled [#controlled]

A tour with controlled state management, allowing external control of the current step.

<ComponentTabs name="tour-controlled-demo" />

### Custom Spotlight Styling [#custom-spotlight-styling]

You can customize the appearance of the spotlighted element using the `SpotlightRing` component:

```tsx
<Tour.Root open={open} onOpenChange={setOpen}>
  <Tour.Portal>
    <Tour.Spotlight />
    {/* Border style */}
    <Tour.SpotlightRing className="rounded-lg border-2 border-primary" />
    {/* Ring with offset */}
    <Tour.SpotlightRing className="rounded-xl ring-2 ring-blue-500 ring-offset-2" />
    {/* Glowing effect */}
    <Tour.SpotlightRing className="rounded-lg shadow-lg shadow-primary/50" />
    {/* Animated pulse */}
    <Tour.SpotlightRing className="rounded-lg border-2 border-primary animate-pulse" />
    <Tour.Step target="#element">{/* ... */}</Tour.Step>
  </Tour.Portal>
</Tour.Root>
```

### Global Offset Control [#global-offset-control]

Set default spacing for all steps and override per step:

```tsx
<Tour.Root
  open={open}
  onOpenChange={setOpen}
  sideOffset={16}      // Global default: 16px gap
  alignOffset={0}      // Global alignment offset
>
  <Tour.Portal>
    <Tour.Spotlight />
    <Tour.SpotlightRing />
    
    {/* Uses global sideOffset={16} */}
    <Tour.Step target="#step-1" side="bottom">
      <Tour.Header>
        <Tour.Title>Step 1</Tour.Title>
      </Tour.Header>
    </Tour.Step>
    
    {/* Overrides with custom sideOffset={32} */}
    <Tour.Step target="#step-2" side="top" sideOffset={32}>
      <Tour.Header>
        <Tour.Title>Step 2 - Larger Gap</Tour.Title>
      </Tour.Header>
    </Tour.Step>
  </Tour.Portal>
</Tour.Root>
```

## API Reference [#api-reference]

### Tour [#tour]

The main container component for the tour that manages state and provides context.

<AutoTypeTable path="./types/base/tour.ts" name="TourProps" />

### TourSpotlight [#tourspotlight]

The spotlight backdrop that dims the page and highlights the target element with a cutout effect.

<AutoTypeTable path="./types/base/tour.ts" name="TourSpotlightProps" />

<DataAttributesTable
  attributes="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### TourSpotlightRing [#tourspotlightring]

A visual ring/border element that wraps around the spotlighted target element. Use this to add custom styling like borders, shadows, or animations to the highlighted area.

<AutoTypeTable path="./types/base/tour.ts" name="TourSpotlightRingProps" />

<DataAttributesTable
  attributes="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### TourStep [#tourstep]

A single step in the tour that targets a specific element on the page.

<AutoTypeTable path="./types/base/tour.ts" name="TourStepProps" />

<DataAttributesTable
  attributes="[
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
]"
/>

### TourClose [#tourclose]

Button to close the entire tour.

<AutoTypeTable path="./types/base/tour.ts" name="TourCloseProps" />

### TourHeader [#tourheader]

Container for the tour step's title and description.

<AutoTypeTable path="./types/base/tour.ts" name="TourHeaderProps" />

### TourTitle [#tourtitle]

The title of the current tour step.

<AutoTypeTable path="./types/base/tour.ts" name="TourTitleProps" />

### TourDescription [#tourdescription]

The description text for the current tour step.

<AutoTypeTable path="./types/base/tour.ts" name="TourDescriptionProps" />

### TourFooter [#tourfooter]

Container for tour navigation controls and step counter.

<AutoTypeTable path="./types/base/tour.ts" name="TourFooterProps" />

### TourStepCounter [#tourstepcounter]

Displays the current step number and total steps.

<AutoTypeTable path="./types/base/tour.ts" name="TourStepCounterProps" />

### TourPrev [#tourprev]

Button to navigate to the previous step.

<AutoTypeTable path="./types/base/tour.ts" name="TourPrevProps" />

### TourNext [#tournext]

Button to navigate to the next step or complete the tour.

<AutoTypeTable path="./types/base/tour.ts" name="TourNextProps" />

### TourSkip [#tourskip]

Button to skip the entire tour.

<AutoTypeTable path="./types/base/tour.ts" name="TourSkipProps" />

### TourArrow [#tourarrow]

An optional arrow element that points to the target element.

<AutoTypeTable path="./types/base/tour.ts" name="TourArrowProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Triggers the onEscapeKeyDown callback. Default behavior closes the tour unless prevented.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element within the tour content.&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element within the tour content.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Activates the focused button (next, previous, skip, or close).&#x22;,
  },
]"
/>

## Credits [#credits]

* [Radix UI Dismissable Layer](https://github.com/radix-ui/primitives/blob/main/packages/react/dismissable-layer/src/dismissable-layer.tsx) - For the pointer down outside and interact outside event handling patterns.
* [Radix UI Focus Guard](https://github.com/radix-ui/primitives/blob/main/packages/react/focus-guards/src/focus-guards.tsx) - For the focus guard implementation.
* [Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog) - For the focus trap and auto-focus management patterns.


# Action Bar
URL: /docs/components/radix/action-bar



<ComponentTabs name="action-bar-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/action-bar"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the portal component into your 

        `components/portal.tsx`

         file.
      </Step>

      <ComponentSource name="portal" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="action-bar" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import {
  ActionBar,
  ActionBarSelection,
  ActionBarSeparator,
  ActionBarGroup,
  ActionBarItem,
  ActionBarClose,
} from "@/components/ui/action-bar";

return (
  <ActionBar>
    <ActionBarSelection />
    <ActionBarSeparator />
    <ActionBarGroup>
      <ActionBarItem />
      <ActionBarItem />
    </ActionBarGroup>
    <ActionBarClose />
  </ActionBar>
);
```

## Examples [#examples]

### Position [#position]

Use the `side` and `align` props to control where the action bar appears.

<ComponentTabs name="action-bar-position-demo" />

## API Reference [#api-reference]

### ActionBar [#actionbar]

The root component that controls the visibility and position of the action bar. Has `role="toolbar"` for accessibility.

<AutoTypeTable path="./types/radix/action-bar.ts" name="ActionBarProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;bottom&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ActionBarSelection [#actionbarselection]

Displays selection information, typically used to show how many items are selected.

<AutoTypeTable path="./types/radix/action-bar.ts" name="ActionBarSelectionProps" />

### ActionBarGroup [#actionbargroup]

A container for action items that implements roving focus management. Items within a group can be navigated using arrow keys, forming a single tab stop. See [Keyboard Interactions](#keyboard-interactions) for full details.

<AutoTypeTable path="./types/radix/action-bar.ts" name="ActionBarGroupProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ActionBarItem [#actionbaritem]

An interactive button item within the action bar. When used inside a `Group`, participates in roving focus navigation.

<AutoTypeTable path="./types/radix/action-bar.ts" name="ActionBarItemProps" />

### ActionBarClose [#actionbarclose]

A button that closes the action bar by calling the `onOpenChange` callback with `false`. The close button has its own tab stop, separate from the group's roving focus.

<AutoTypeTable path="./types/radix/action-bar.ts" name="ActionBarCloseProps" />

### ActionBarSeparator [#actionbarseparator]

A visual separator between action bar items.

<AutoTypeTable path="./types/radix/action-bar.ts" name="ActionBarSeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

The action bar follows the [WAI-ARIA Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) for keyboard navigation.

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element (Action Group or Close button).&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the action bar and calls onOpenChange(false).&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves focus to the previous item in the group (horizontal orientation).&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves focus to the previous item in the group (vertical orientation).&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves focus to the next item in the group (horizontal orientation).&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves focus to the next item in the group (vertical orientation).&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves focus to the first item in the group.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves focus to the last item in the group.&#x22;,
  },
]"
/>


# Angle Slider
URL: /docs/components/radix/angle-slider



<ComponentTabs name="angle-slider-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/angle-slider
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="angle-slider" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  AngleSlider,
  AngleSliderRange,
  AngleSliderThumb,
  AngleSliderTrack,
  AngleSliderValue,
} from "@/components/ui/angle-slider";

return (
  <AngleSlider>
    <AngleSliderTrack>
      <AngleSliderRange />
    </AngleSliderTrack>
    <AngleSliderThumb />
    <AngleSliderValue />
  </AngleSlider>
)
```

## Examples [#examples]

### **Controlled** State [#controlled-state]

A slider with controlled state management and custom actions.

<ComponentTabs name="angle-slider-controlled-demo" />

### Range Selection [#range-selection]

Use multiple thumbs to create angle ranges with minimum step constraints.

<ComponentTabs name="angle-slider-range-demo" />

### Themes [#themes]

Slider variants with different themes.

<ComponentTabs name="angle-slider-themes-demo" />

### With Form [#with-form]

Integrate the angle slider with form validation and submission.

<ComponentTabs name="angle-slider-form-demo" />

## Theming [#theming]

You can customize the appearance by targeting specific components:

### Track Theming [#track-theming]

Use `[&>[data-slot='angle-slider-track-rail']]` to style the background track:

```tsx
<AngleSliderTrack className="*:data-[slot='angle-slider-track-rail']:stroke-green-100" />
```

### Range Theming [#range-theming]

```tsx
<AngleSliderRange className="stroke-green-500" />
```

### Thumb Theming [#thumb-theming]

```tsx
<AngleSliderThumb className="border-green-500 bg-green-50 ring-green-500/50" />
```

### Value Theming [#value-theming]

```tsx
<AngleSliderValue className="text-green-600 dark:text-green-400" />
```

## API Reference [#api-reference]

### AngleSlider [#angleslider]

The main container component for the angle slider.

<AutoTypeTable path="./types/radix/angle-slider.ts" name="AngleSliderProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

### AngleSliderTrack [#angleslidertrack]

The circular track that represents the full range of possible values.

<AutoTypeTable path="./types/radix/angle-slider.ts" name="AngleSliderTrackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
  {
    title: &#x22;[data-slot='angle-slider-track-rail']&#x22;,
    value: &#x22;Present on the rail of the track.&#x22;,
  },
]"
/>

### AngleSliderRange [#anglesliderrange]

The portion of the track that represents the selected range.

<AutoTypeTable path="./types/radix/angle-slider.ts" name="AngleSliderRangeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

### AngleSliderThumb [#anglesliderthumb]

The draggable handle for selecting values.

<AutoTypeTable path="./types/radix/angle-slider.ts" name="AngleSliderThumbProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

### AngleSliderValue [#angleslidervalue]

Displays the current value(s) with customizable formatting.

<AutoTypeTable path="./types/radix/angle-slider.ts" name="AngleSliderValueProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the angle slider is disabled.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

The angle slider component includes comprehensive accessibility features:

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowRight&#x22;],
    description: &#x22;Increase the value by one step.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;, &#x22;ArrowLeft&#x22;],
    description: &#x22;Decrease the value by one step.&#x22;,
  },
  {
    keys: [&#x22;PageUp&#x22;],
    description: &#x22;Increase the value by ten steps.&#x22;,
  },
  {
    keys: [&#x22;PageDown&#x22;],
    description: &#x22;Decrease the value by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Shift + Arrow Keys&#x22;],
    description: &#x22;Increase/decrease the value by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Set the value to the minimum.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Set the value to the maximum.&#x22;,
  },
]"
/>

## Features [#features]

* Optimized for touch interactions on mobile devices
* Smooth dragging experience with proper pointer handling
* Full right-to-left language support
* Comprehensive keyboard navigation and screen reader support
* Angle ranges with minimum step constraints with multiple thumbs
* Controlled and uncontrolled state management


# Avatar Group
URL: /docs/components/radix/avatar-group



<ComponentTabs name="avatar-group-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/avatar-group

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="avatar-group" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import { AvatarGroup } from "@/components/ui/avatar-group";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";

<AvatarGroup>
  <Avatar>
    <AvatarImage src="/tony-hawk.png" />
    <AvatarFallback>TH</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/rodney-mullen.png" />
    <AvatarFallback>RM</AvatarFallback>
  </Avatar>
</AvatarGroup>
```

## Examples [#examples]

### With Truncation [#with-truncation]

Automatically truncate long lists and show overflow indicators with the `max` prop.

<ComponentTabs name="avatar-group-truncation-demo" />

### With RTL [#with-rtl]

Support for right-to-left layouts and vertical RTL stacking.

<ComponentTabs name="avatar-group-rtl-demo" />

### With Icons [#with-icons]

Use the Avatar Group component with icons or other elements beyond avatars.

<ComponentTabs name="avatar-group-icons-demo" />

### Custom Overflow [#custom-overflow]

Customize the overflow indicator with the `renderOverflow` prop.

<ComponentTabs name="avatar-group-custom-overflow-demo" />

## API Reference [#api-reference]

### AvatarGroup [#avatargroup]

The main avatar group container that handles layout and masking of child elements.

<AutoTypeTable path="./types/radix/avatar-group.ts" name="AvatarGroupProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>


# Badge Overflow
URL: /docs/components/radix/badge-overflow



<ComponentTabs name="badge-overflow-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/badge-overflow

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="badge-overflow" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import { Badge } from "@/components/ui/badge";
import { BadgeOverflow } from "@/components/ui/badge-overflow";

<BadgeOverflow renderBadge={(_, label) => <Badge>{label}</Badge>} />
```

## Usage [#usage]

### With Primitive Arrays [#with-primitive-arrays]

When using primitive arrays (strings, numbers), the `getBadgeLabel` prop is optional. The component will automatically use the item itself as the label.

```tsx
<BadgeOverflow
  items={["React", "TypeScript", "Next.js"]}
  renderBadge={(item, label) => <Badge>{label}</Badge>}
/>
```

### With Object Arrays [#with-object-arrays]

When using object arrays, the `getBadgeLabel` prop is required to extract the label from each item.

```tsx
<BadgeOverflow
  items={[
    { id: 1, name: "React" },
    { id: 2, name: "TypeScript" },
  ]}
  getBadgeLabel={(item) => item.name}
  renderBadge={(item, label) => <Badge>{label}</Badge>}
/>
```

## Examples [#examples]

### Multi-line Overflow [#multi-line-overflow]

Display badges across multiple lines using the `lineCount` prop.

<ComponentTabs name="badge-overflow-multiline-demo" />

### Interactive Tags [#interactive-tags]

Interactive demo showing how to add and remove tags with overflow handling.

<ComponentTabs name="badge-overflow-interactive-demo" />

## API Reference [#api-reference]

### BadgeOverflow [#badgeoverflow]

The component that measures available space and displays badges with overflow indicators.

<AutoTypeTable path="./types/radix/badge-overflow.ts" name="BadgeOverflowProps" />

## Features [#features]

### Automatic Width Measurement [#automatic-width-measurement]

The component automatically measures badge widths using DOM measurement and caches results for performance. This ensures accurate overflow calculations without manual configuration.

### Computed Container Styles [#computed-container-styles]

The component automatically extracts container padding, gap, badge height, and overflow badge width from computed styles. This means it adapts seamlessly to your CSS without requiring manual prop configuration.

### Multi-line Support [#multi-line-support]

Control how many lines of badges to display using the `lineCount` prop. The component will intelligently wrap badges across lines while respecting the overflow constraints.

### Custom Rendering [#custom-rendering]

Use `renderBadge` and `renderOverflow` props to fully customize how badges and overflow indicators are rendered, allowing complete control over styling and behavior.

### Performance Optimization [#performance-optimization]

The component renders all badges invisibly to measure their actual widths, then uses those measurements to determine which badges fit within the specified line count. ResizeObserver efficiently responds to container size changes.

## Notes [#notes]

* The component measures actual rendered badges to calculate widths accurately (including icons, custom styling, etc.)
* Container styles (padding, gap, badge height, overflow width) are automatically computed from CSS
* Measurements update automatically when items change or container is resized
* Container must have a defined width for overflow calculations to work


# Banner
URL: /docs/components/radix/banner



<ComponentTabs name="banner-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/banner"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-value-as-ref" />

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="banner" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import {
  Banner,
  BannerIcon,
  BannerContent,
  BannerTitle,
  BannerDescription,
  BannerActions,
  BannerClose,
} from "@/components/ui/banner";

return (
  <Banner>
    <BannerIcon />
    <BannerContent>
      <BannerTitle />
      <BannerDescription />
    </BannerContent>
    <BannerActions />
    <BannerClose />
  </Banner>
);
```

## Examples [#examples]

### Stacked Banners [#stacked-banners]

Use the `Banners` provider to manage multiple banners with a queue system. Banners can be added imperatively using the `useBanners` hook.

<ComponentTabs name="banner-stacked-demo" />

## API Reference [#api-reference]

### Banners [#banners]

The root provider for managing a queue of banners. Wrap your application or a section to enable banner queuing.

<AutoTypeTable path="./types/radix/banner.ts" name="BannersProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;bottom&#x22;],
  },
]"
/>

### Banner [#banner]

An individual banner component. Can be used standalone or within the `Banners` provider.

<AutoTypeTable path="./types/radix/banner.ts" name="BannerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### BannerIcon [#bannericon]

Container for the banner's icon.

<AutoTypeTable path="./types/radix/banner.ts" name="BannerIconProps" />

### BannerContent [#bannercontent]

Container for the banner's text content (title and description).

<AutoTypeTable path="./types/radix/banner.ts" name="BannerContentProps" />

### BannerTitle [#bannertitle]

The banner's title text.

<AutoTypeTable path="./types/radix/banner.ts" name="BannerTitleProps" />

### BannerDescription [#bannerdescription]

The banner's description text.

<AutoTypeTable path="./types/radix/banner.ts" name="BannerDescriptionProps" />

### BannerActions [#banneractions]

Container for action buttons.

<AutoTypeTable path="./types/radix/banner.ts" name="BannerActionsProps" />

### BannerClose [#bannerclose]

A button that dismisses the banner. Uses the shadcn Button component internally.

<AutoTypeTable path="./types/radix/banner.ts" name="BannerCloseProps" />

### useBanners [#usebanners]

Hook to access banner queue management within a `Banners` provider.

<AutoTypeTable path="./types/radix/banner.ts" name="UseBannersReturn" />

### useBanner [#usebanner]

Hook to access the current banner's context (id, variant, dismissible state, and close handler).

<AutoTypeTable path="./types/radix/banner.ts" name="UseBannerReturn" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element within the banner.&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element within the banner.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Activates the focused button.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Activates the focused button.&#x22;,
  },
]"
/>


# Checkbox Group
URL: /docs/components/radix/checkbox-group



<ComponentTabs name="checkbox-group-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/checkbox-group
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/checkbox-group
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/checkbox-group
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/checkbox-group
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/checkbox-group
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/checkbox-group
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/checkbox-group
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/checkbox-group
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/checkbox-group
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="checkbox-group" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  CheckboxGroup,
  CheckboxGroupLabel,
  CheckboxGroupList,
  CheckboxGroupItem,
  CheckboxGroupIndicator,
  CheckboxGroupDescription,
} from "@diceui/checkbox-group";

return (
  <CheckboxGroup>
    <CheckboxGroupLabel />
    <CheckboxGroupList>
      <CheckboxGroupItem>
        <CheckboxGroupIndicator />
      </CheckboxGroupItem>
    </CheckboxGroupList>
    <CheckboxGroupDescription>
  </CheckboxGroup>
)
```

## Animated Checkbox [#animated-checkbox]

<Steps>
  <Step>
    Update `tailwind.config.ts` to include the following animation:

    ```ts
    export default {
      theme: {
        extend: {
          keyframes: {
            "stroke-dashoffset": {
              "0%": { strokeDashoffset: "100%" },
              "100%": { strokeDashoffset: "0" },
            },
          },
          animation: {
            "stroke-dashoffset": "stroke-dashoffset 0.2s linear forwards",
          },
        },
      },
    }
    ```
  </Step>

  <Step>
    Copy and paste the `CheckboxGroupIndicator` block from the following example into your project.

    <ComponentTabs name="checkbox-group-animated-demo" />
  </Step>
</Steps>

## Examples [#examples]

### Horizontal Orientation [#horizontal-orientation]

<ComponentTabs name="checkbox-group-horizontal-demo" />

### With Validation [#with-validation]

Validate the group with `onValidate` or `required` prop. Can be used for native form validation.

<ComponentTabs name="checkbox-group-validation-demo" />

### Multi Selection [#multi-selection]

Hold down the `Shift` key to select and deselect multiple checkboxes at once.

<ComponentTabs name="checkbox-group-multi-selection-demo" />

## API Reference [#api-reference]

### CheckboxGroup [#checkboxgroup]

Container for the checkbox group.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

### CheckboxGroupLabel [#checkboxgrouplabel]

Label for the checkbox group.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="LabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### CheckboxGroupList [#checkboxgrouplist]

Container for checkbox items.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="ListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

### CheckboxGroupItem [#checkboxgroupitem]

Individual checkbox item.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;checked&#x22;, &#x22;unchecked&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

### CheckboxGroupIndicator [#checkboxgroupindicator]

Visual indicator for the checkbox state.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="IndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;checked&#x22;, &#x22;unchecked&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### CheckboxGroupDescription [#checkboxgroupdescription]

Optional description text for the checkbox group.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="DescriptionProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

### CheckboxGroupMessage [#checkboxgroupmessage]

Error or validation message for the checkbox group.

<AutoTypeTable path="./types/radix/checkbox-group.ts" name="MessageProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Toggles checkbox item.&#x22;
  },
]"
/>


# Circular Progress
URL: /docs/components/radix/circular-progress



<ComponentTabs name="circular-progress-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/circular-progress
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="circular-progress" />

      <Step>
        Add the following CSS animations to your 

        `globals.css`

         file:
      </Step>

      ```css
      @theme {
        --animate-spin-around: spin-around 0.8s linear infinite;

        @keyframes spin-around {
          0% {
            transform: rotate(-90deg);
          }
          100% {
            transform: rotate(270deg);
          }
        }
      }
      ```
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  CircularProgress,
  CircularProgressIndicator,
  CircularProgressTrack,
  CircularProgressRange,
  CircularProgressValueText,
} from "@/components/ui/circular-progress";

return (
  <CircularProgress>
    <CircularProgressIndicator>
      <CircularProgressTrack />
      <CircularProgressRange />
    </CircularProgressIndicator>
    <CircularProgressValueText />
  </CircularProgress>
)
```

Or use the `Combined` component to get all the parts in one.

```tsx
import { CircularProgressCombined } from "@/components/ui/circular-progress";

<CircularProgressCombined />
```

## Examples [#examples]

### Interactive Demo [#interactive-demo]

A circular progress with interactive controls and simulated upload progress.

<ComponentTabs name="circular-progress-interactive-demo" />

### Colors [#colors]

Different color themes using Tailwind CSS stroke and text utilities to customize the track, range, and value text colors.

<ComponentTabs name="circular-progress-colors-demo" />

## Theming [#theming]

The circular progress component uses CSS `currentColor` for stroke colors, making it easy to theme using Tailwind's text or stroke utilities:

### Track Theming [#track-theming]

```tsx
<CircularProgressTrack className="text-green-200 dark:text-green-900" />
```

### Range Theming [#range-theming]

```tsx
<CircularProgressRange className="text-green-500" />
```

### Value Text Theming [#value-text-theming]

```tsx
<CircularProgressValueText className="text-green-700 dark:text-green-300" />
```

### Custom Stroke Styles [#custom-stroke-styles]

You can also use Tailwind's stroke utilities directly:

```tsx
<CircularProgressTrack className="stroke-blue-200" />
<CircularProgressRange className="stroke-blue-500" />
```

## API Reference [#api-reference]

### CircularProgress [#circularprogress]

The main container component for the circular progress.

<AutoTypeTable path="./types/radix/circular-progress.ts" name="CircularProgressProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current progress value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum progress value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum progress value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### CircularProgressIndicator [#circularprogressindicator]

The SVG container that holds the circular progress tracks and ranges.

<AutoTypeTable path="./types/radix/circular-progress.ts" name="CircularProgressIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current progress value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum progress value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum progress value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized progress value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### CircularProgressTrack [#circularprogresstrack]

The background circle that represents the full range of possible values.

<AutoTypeTable path="./types/radix/circular-progress.ts" name="CircularProgressTrackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### CircularProgressRange [#circularprogressrange]

The portion of the circle that represents the current progress value.

<AutoTypeTable path="./types/radix/circular-progress.ts" name="CircularProgressRangeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current progress value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum progress value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum progress value.&#x22;,
  },
]"
/>

### CircularProgressValueText [#circularprogressvaluetext]

The text element that displays the current progress value or custom content.

<AutoTypeTable path="./types/radix/circular-progress.ts" name="CircularProgressValueTextProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### CircularProgressCombined [#circularprogresscombined]

The combined component that includes all the parts.

<AutoTypeTable path="./types/radix/circular-progress.ts" name="CircularProgressProps" />

## Accessibility [#accessibility]

### Screen Reader Support [#screen-reader-support]

* Uses the `progressbar` role for proper screen reader identification
* Provides `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` attributes
* Supports indeterminate state by omitting `aria-valuenow` when value is null

## Notes [#notes]

* The component automatically handles indeterminate states when `value` is `null` or `undefined`
* Progress values are automatically clamped to the valid range between `min` and `max`
* Invalid `max` or `value` props will log console errors and use fallback values
* The indeterminate animation uses CSS custom properties and can be customized via the `--animate-spin-around` variable
* All stroke colors use `currentColor` by default, making them responsive to text color changes


# Color Picker
URL: /docs/components/radix/color-picker



<ComponentTabs name="color-picker-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/color-picker
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="color-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ColorPicker,
  ColorPickerAlphaSlider,
  ColorPickerArea,
  ColorPickerContent,
  ColorPickerEyeDropper,
  ColorPickerFormatSelect,
  ColorPickerHueSlider,
  ColorPickerInput,
  ColorPickerSwatch,
  ColorPickerTrigger,
} from "@/components/ui/color-picker";

return (
  <ColorPicker>
    <ColorPickerTrigger>
      <ColorPickerSwatch />
    </ColorPickerTrigger>
    <ColorPickerContent>
      <ColorPickerArea />
      <ColorPickerEyeDropper />
      <ColorPickerHueSlider />
      <ColorPickerAlphaSlider />
      <ColorPickerFormatSelect />
      <ColorPickerInput />
    </ColorPickerContent>
  </ColorPicker>
)
```

## Examples [#examples]

### Inline Color Picker [#inline-color-picker]

Use the `inline` prop to render the color picker inline instead of in a popover.

<ComponentTabs name="color-picker-inline-demo" />

### Controlled State [#controlled-state]

A color picker with controlled state management.

<ComponentTabs name="color-picker-controlled-demo" />

### With Form [#with-form]

A color picker with form integration.

<ComponentTabs name="color-picker-form-demo" />

## API Reference [#api-reference]

### ColorPicker [#colorpicker]

The main container component for the color picker.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerProps" />

### ColorPickerTrigger [#colorpickertrigger]

The trigger button that opens the color picker popover.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerTriggerProps" />

### ColorPickerContent [#colorpickercontent]

The content container for the color picker components.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerContentProps" />

### ColorPickerArea [#colorpickerarea]

The 2D color area for selecting hue and saturation.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerAreaProps" />

### ColorPickerSwatch [#colorpickerswatch]

A color swatch that displays the current color.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerSwatchProps" />

### ColorPickerHueSlider [#colorpickerhueslider]

A slider for adjusting the hue value of the color.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerHueSliderProps" />

### ColorPickerAlphaSlider [#colorpickeralphaslider]

A slider for adjusting the alpha (transparency) value of the color.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerAlphaSliderProps" />

### ColorPickerEyeDropper [#colorpickereyedropper]

A button that activates the browser's native eye dropper tool to pick colors from the screen.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerEyeDropperProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the component is disabled.&#x22;,
  },
]"
/>

**Note:** The EyeDropper component only renders when the browser supports the native EyeDropper API. It will return `null` in unsupported browsers.

### ColorPickerFormatSelect [#colorpickerformatselect]

A select dropdown for choosing the color format (hex, rgb, hsl, hsb).

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerFormatSelectProps" />

### ColorPickerInput [#colorpickerinput]

An input field that displays and allows editing of the color value in the selected format.

<AutoTypeTable path="./types/radix/color-picker.ts" name="ColorPickerInputProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Opens the color picker when focus is on the trigger.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the color picker and moves focus to the trigger.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowDown&#x22;, &#x22;ArrowLeft&#x22;, &#x22;ArrowRight&#x22;],
    description: &#x22;Adjusts the color value when focus is on sliders or the color area.&#x22;,
  },
]"
/>

## Browser Support [#browser-support]

### EyeDropper API [#eyedropper-api]

The EyeDropper component requires browser support for the native EyeDropper API:

* **Chrome/Edge**: Supported from version 95+
* **Firefox**: Not supported
* **Safari**: Not supported

The component gracefully handles unsupported browsers by not rendering the eye dropper button.

## Color Formats [#color-formats]

The color picker supports the following color formats:

* **HEX**: Hexadecimal color notation (e.g., `#3b82f6`)
* **RGB**: Red, Green, Blue color notation (e.g., `rgb(59, 130, 246)`)
* **HSL**: Hue, Saturation, Lightness color notation (e.g., `hsl(217, 91%, 60%)`)
* **HSB**: Hue, Saturation, Brightness color notation (e.g., `hsb(217, 76%, 96%)`)

All formats support alpha channel for transparency when not using the `withoutAlpha` prop.


# Color Swatch
URL: /docs/components/radix/color-swatch



<ComponentTabs name="color-swatch-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/color-swatch

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="color-swatch" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

Import the component and use it to display color values.

```tsx
import { ColorSwatch } from "@/components/ui/color-swatch";

<ColorSwatch value="#3b82f6" />
```

## Examples [#examples]

### Different Sizes [#different-sizes]

The color swatch component supports three different sizes: `sm`, `default`, and `lg`.

<ComponentTabs name="color-swatch-sizes-demo" />

### Transparency Support [#transparency-support]

The color swatch automatically detects transparent colors and displays them with a checkerboard background pattern.

<ComponentTabs name="color-swatch-transparency-demo" />

## API Reference [#api-reference]

### ColorSwatch [#colorswatch]

A color swatch component that displays a color value with optional transparency support.

<AutoTypeTable path="./types/radix/color-swatch.ts" name="ColorSwatchProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the component is disabled.&#x22;,
  },
  {
    title: &#x22;[data-slot]&#x22;,
    value: &#x22;Always set to 'color-swatch' for identification.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

The color swatch component includes proper accessibility features:

* **ARIA Label**: Automatically generates descriptive `aria-label` text based on the color value
* **Role**: Uses `role="img"` to indicate it's an image representation of a color
* **Disabled State**: Properly handles disabled state with appropriate visual and interaction changes

### Screen Reader Support [#screen-reader-support]

* When a color value is provided, the `aria-label` reads "Color swatch: \[color-value]"
* When no color is selected, the `aria-label` reads "No color selected"

## Color Format Support [#color-format-support]

The color swatch component supports various color formats:

* **HEX**: `#3b82f6`
* **RGB**: `rgb(59, 130, 246)`
* **RGBA**: `rgba(59, 130, 246, 0.5)`
* **HSL**: `hsl(217, 91%, 60%)`
* **HSLA**: `hsla(217, 91%, 60%, 0.5)`
* **Named Colors**: `blue`, `red`, etc.

## Transparency Detection [#transparency-detection]

The component automatically detects transparent colors by checking for:

* `rgba()` or `hsla()` function notation
* RGB/HSL with 4 values (including alpha)
* Any color format that includes transparency information

When transparency is detected, a checkerboard pattern is displayed behind the color to show the transparency effect. Use the `withoutTransparency` prop to disable this behavior.


# Combobox
URL: /docs/components/radix/combobox



<ComponentTabs name="combobox-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/combobox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/combobox
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/combobox
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/combobox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/combobox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/combobox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/combobox
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="combobox" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Combobox,
  ComboboxLabel,
  ComboboxAnchor,
  ComboboxBadgeList,
  ComboboxBadgeItem,
  ComboboxBadgeItemDelete,
  ComboboxInput,
  ComboboxTrigger,
  ComboboxCancel,
  ComboboxPortal,
  ComboboxContent,
  ComboboxArrow,
  ComboboxLoading,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxItem,
  ComboboxItemText,
  ComboboxItemIndicator,
  ComboboxSeparator,
} from "@diceui/combobox";

return (
  <Combobox>
    <ComboboxLabel />
    <ComboboxAnchor>
      <ComboboxBadgeList>
        <ComboboxBadgeItem>
          <ComboboxBadgeItemDelete />
        </ComboboxBadgeItem>
      </ComboboxBadgeList>
      <ComboboxInput />
      <ComboboxTrigger />
      <ComboboxCancel />
    </ComboboxAnchor>
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxArrow />
        <ComboboxLoading />
        <ComboboxEmpty />
        <ComboboxGroup>
          <ComboboxGroupLabel />
          <ComboboxItem>
            <ComboboxItemText />
            <ComboboxItemIndicator />
          </ComboboxItem>
        </ComboboxGroup>
        <ComboboxSeparator />
      </ComboboxContent>
    </ComboboxPortal>
  </Combobox>
)
```

## Examples [#examples]

### With Groups [#with-groups]

<ComponentTabs name="combobox-groups-demo" />

### With Multiple Selection [#with-multiple-selection]

<ComponentTabs name="combobox-multiple-demo" />

### With Custom Filter [#with-custom-filter]

<ComponentTabs name="combobox-custom-filter-demo" />

### With Debounce [#with-debounce]

<ComponentTabs name="combobox-debounced-demo" />

### With Virtualization [#with-virtualization]

<ComponentTabs name="combobox-virtualized-demo" />

### With Tags Input [#with-tags-input]

<ComponentTabs name="combobox-tags-demo" />

## API Reference [#api-reference]

### Combobox [#combobox]

The container for all combobox parts.

<AutoTypeTable path="./types/radix/combobox.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
]"
/>

### ComboboxLabel [#comboboxlabel]

An accessible label that describes the combobox. Associates with the input element for screen readers.

<AutoTypeTable path="./types/radix/combobox.ts" name="LabelProps" />

### ComboboxAnchor [#comboboxanchor]

A wrapper element that positions the combobox popover relative to the input and trigger. Provides the reference point for popover positioning.

<AutoTypeTable path="./types/radix/combobox.ts" name="AnchorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-anchor]&#x22;,
    value: &#x22;Present when the anchor is present&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-focused]&#x22;,
    value: &#x22;Present when the anchor is focused&#x22;,
  },
]"
/>

### ComboboxTrigger [#comboboxtrigger]

A button that toggles the combobox popover. Handles focus management and keyboard interactions for opening/closing the popover.

<AutoTypeTable path="./types/radix/combobox.ts" name="TriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
]"
/>

### ComboboxInput [#comboboxinput]

The text input field that users can type into to filter options.

<AutoTypeTable path="./types/radix/combobox.ts" name="InputProps" />

### ComboboxBadgeList [#comboboxbadgelist]

A container for displaying selected items as badges in a multi-select combobox.

<AutoTypeTable path="./types/radix/combobox.ts" name="BadgeListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ComboboxBadgeItem [#comboboxbadgeitem]

An individual badge representing a selected item in a multi-select combobox.

<AutoTypeTable path="./types/radix/combobox.ts" name="BadgeItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the badge is disabled&#x22;,
  },
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the badge is highlighted&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### ComboboxBadgeItemDelete [#comboboxbadgeitemdelete]

A button to remove a selected item from the multi-select combobox.

<AutoTypeTable path="./types/radix/combobox.ts" name="BadgeItemDeleteProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the parent badge is disabled&#x22;,
  },
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the parent badge is highlighted&#x22;,
  },
]"
/>

### ComboboxCancel [#comboboxcancel]

A button that clears the input value and resets the filter.

<AutoTypeTable path="./types/radix/combobox.ts" name="CancelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
]"
/>

### ComboboxPortal [#comboboxportal]

A portal for rendering the combobox content outside of its DOM hierarchy.

<AutoTypeTable path="./types/radix/combobox.ts" name="PortalProps" />

### ComboboxContent [#comboboxcontent]

The popover container for combobox items. Positions the combobox popover relative to the anchor.

<AutoTypeTable path="./types/radix/combobox.ts" name="ContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--dice-transform-origin&#x22;,
    description: &#x22;Transform origin for anchor positioning.&#x22;,
  },
  {
    title: &#x22;--dice-anchor-width&#x22;,
    description: &#x22;Width of the anchor element.&#x22;,
  },
  {
    title: &#x22;--dice-anchor-height&#x22;,
    description: &#x22;Height of the anchor element.&#x22;,
  },
  {
    title: &#x22;--dice-available-width&#x22;,
    description: &#x22;Available width in the viewport for the popover element.&#x22;,
  },
  {
    title: &#x22;--dice-available-height&#x22;,
    description: &#x22;Available height in the viewport for the popover element.&#x22;,
  },
]"
/>

### ComboboxArrow [#comboboxarrow]

A visual arrow element that points to the anchor.

<AutoTypeTable path="./types/radix/combobox.ts" name="ArrowProps" />

### ComboboxLoading [#comboboxloading]

A loading indicator for asynchronous filtering operations.

<AutoTypeTable path="./types/radix/combobox.ts" name="LoadingProps" />

### ComboboxEmpty [#comboboxempty]

A placeholder component displayed when no options match the current filter.

<AutoTypeTable path="./types/radix/combobox.ts" name="EmptyProps" />

### ComboboxGroup [#comboboxgroup]

A container for logically grouping related options.

<AutoTypeTable path="./types/radix/combobox.ts" name="GroupProps" />

### ComboboxGroupLabel [#comboboxgrouplabel]

A label that describes a group of options.

<AutoTypeTable path="./types/radix/combobox.ts" name="GroupLabelProps" />

### ComboboxItem [#comboboxitem]

An interactive item in the combobox list.

<AutoTypeTable path="./types/radix/combobox.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the item is highlighted&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;checked&#x22;, &#x22;unchecked&#x22;],
  },
]"
/>

### ComboboxItemText [#comboboxitemtext]

The textual content of an item.

<AutoTypeTable path="./types/radix/combobox.ts" name="ItemTextProps" />

### ComboboxItemIndicator [#comboboxitemindicator]

A visual indicator for selected options.

<AutoTypeTable path="./types/radix/combobox.ts" name="ItemIndicatorProps" />

### ComboboxSeparator [#comboboxseparator]

A visual divider for separating options or groups.

<AutoTypeTable path="./types/radix/combobox.ts" name="SeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When open, selects the highlighted option. When a badge is highlighted in multiple mode, removes the badge.&#x22;
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;When open, highlights the previous option.&#x22;
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;When open, highlights the next option.&#x22;
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;In multiple mode: When cursor is at start of input, closes the menu and highlights the last badge. When a badge is highlighted, moves highlight to previous badge.&#x22;
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;In multiple mode: When a badge is highlighted, moves highlight to next badge. If on last badge, removes highlight and focuses input.&#x22;
  },
  {
    keys: [&#x22;Backspace&#x22;, &#x22;Delete&#x22;],
    description: &#x22;In multiple mode: When input is empty, removes the last badge. When a badge is highlighted, removes the highlighted badge.&#x22;
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;When open, highlights the first option.&#x22;
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;When open, highlights the last option.&#x22;
  },
  {
    keys: [&#x22;PageUp&#x22;],
    description: &#x22;When open and modal is enabled, highlights the previous option.&#x22;
  },
  {
    keys: [&#x22;PageDown&#x22;],
    description: &#x22;When open and modal is enabled, highlights the next option.&#x22;
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the combobox popover, returns focus to the input, and resets or restores the input value.&#x22;
  },
]"
/>


# Command Stack
URL: /docs/components/radix/command-stack



<ComponentTabs name="command-stack-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/command-stack
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the command component from shadcn/ui.
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npx shadcn@latest add command
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm dlx shadcn@latest add command
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn dlx shadcn@latest add command
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun x shadcn@latest add command
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="command-stack" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  CommandStack,
  CommandStackBreadcrumb,
  CommandStackEmpty,
  CommandStackGroup,
  CommandStackInput,
  CommandStackItem,
  CommandStackList,
  CommandStackPage,
  CommandStackShortcut,
} from "@/components/ui/command-stack";

return (
  <CommandStack>
    <CommandStackBreadcrumb />
    <CommandStackInput />
    <CommandStackList>
      <CommandStackEmpty />
      <CommandStackPage value="root">
        <CommandStackGroup>
          <CommandStackItem page="projects">
            <CommandStackShortcut />
          </CommandStackItem>
        </CommandStackGroup>
      </CommandStackPage>
      <CommandStackPage value="projects">
        <CommandStackItem />
      </CommandStackPage>
    </CommandStackList>
  </CommandStack>
)
```

## Examples [#examples]

### Popover [#popover]

Put the stack in a popover for nested menus, such as a filter menu where each filter opens its options. Set `selectionMode` on a page to make its items toggleable, and control the selection with `value` and `onValueChange`. The stack goes back to the root page whenever the popover closes.

<ComponentTabs name="command-stack-popover-demo" />

### Command Palette [#command-palette]

Render the stack inside `CommandDialog` to build a command palette. This example uses the `line` input and opens with <Kbd>⌘ J</Kbd>, since <Kbd>⌘ K</Kbd> opens the docs search.

<ComponentTabs name="command-stack-dialog-demo" />

### Workspace [#workspace]

A workspace menu that nests pages several levels deep, from members to a member's role. Items can show avatars, descriptions and trailing details.

<ComponentTabs name="command-stack-workspace-demo" />

### Async [#async]

Load a page's items when it opens. `useCommandStack` gives access to the active page, and `CommandStackLoading` hides the empty state while items load.

<ComponentTabs name="command-stack-async-demo" />

## API Reference [#api-reference]

### CommandStack [#commandstack]

The root component. It keeps the stack of open pages and the search value, and clears the search whenever the page changes.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackProps" />

### CommandStackBreadcrumb [#commandstackbreadcrumb]

Shows the open pages, using each page's `label`.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackBreadcrumbProps" />

### CommandStackInput [#commandstackinput]

The search input. Pressing <Kbd>Backspace</Kbd> while it's empty goes back a page. Set `variant="line"` for a plain row with a divider below it.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackInputProps" />

### CommandStackList [#commandstacklist]

The scrollable list of pages, groups and items.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackListProps" />

### CommandStackEmpty [#commandstackempty]

Shown when no items match the search. It stays hidden while a `CommandStackLoading` is rendered.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackEmptyProps" />

### CommandStackLoading [#commandstackloading]

Shown while a page's items load.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackLoadingProps" />

### CommandStackPage [#commandstackpage]

A page of items. Only the active page renders its children.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackPageProps" />

### CommandStackGroup [#commandstackgroup]

A group of items with an optional heading.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackGroupProps" />

### CommandStackItem [#commandstackitem]

A selectable item. Set `page` to open a page when it's selected, which also shows a chevron, or give it a `value` on a page with a `selectionMode` to make it toggleable.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackItemProps" />

### CommandStackShortcut [#commandstackshortcut]

A keyboard shortcut hint shown at the end of an item.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackShortcutProps" />

### CommandStackSeparator [#commandstackseparator]

A line between groups.

<AutoTypeTable path="./types/radix/command-stack.ts" name="CommandStackSeparatorProps" />

### useCommandStack [#usecommandstack]

Reads and changes the stack's pages from any component inside it. It returns `pages`, `activePage`, `search`, `value`, `pushPage(page)`, `popPage()`, `setPages(pages)` and `setValue(value)`.

```tsx
import { useCommandStack } from "@/components/ui/command-stack";

function OpenSettings() {
  const { pushPage } = useCommandStack();

  return (
    <CommandStackItem onSelect={() => pushPage("settings")}>
      Settings
    </CommandStackItem>
  );
}
```

## Accessibility [#accessibility]

The input keeps focus while you move between pages. On a nested page, the input shows a back button labelled "Back". The breadcrumb is a labelled navigation landmark that marks the current page, and opening a page announces its label to screen readers.

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowDown&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves the highlight to the next or previous item.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;, &#x22;End&#x22;],
    description: &#x22;Moves the highlight to the first or last item.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Selects the highlighted item, opening its page if it has one.&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;When the input is empty, goes back to the previous page.&#x22;,
  },
]"
/>


# Compare Slider
URL: /docs/components/radix/compare-slider



<ComponentTabs name="compare-slider-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/compare-slider
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="compare-slider" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  CompareSlider,
  CompareSliderBefore,
  CompareSliderAfter,
  CompareSliderHandle,
} from "@/components/ui/compare-slider";

return (
  <CompareSlider>
    <CompareSliderBefore />
    <CompareSliderAfter />
    <CompareSliderHandle />
  </CompareSlider>
)
```

## Examples [#examples]

### Controlled State [#controlled-state]

A compare slider with external controls for the slider position.

<ComponentTabs name="compare-slider-controlled-demo" />

### Vertical Orientation [#vertical-orientation]

A compare slider with vertical orientation, perfect for comparing tall images or content.

<ComponentTabs name="compare-slider-vertical-demo" />

### Customization [#customization]

Compare slider with custom handle, labels, and vertical orientation.

<ComponentTabs name="compare-slider-customization-demo" />

## API Reference [#api-reference]

### CompareSlider [#compareslider]

The root container for the compare slider component.

<AutoTypeTable path="./types/radix/compare-slider.ts" name="CompareSliderProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderBefore [#comparesliderbefore]

The container for the "before" content that appears on the left (or top in vertical mode).

<AutoTypeTable path="./types/radix/compare-slider.ts" name="CompareSliderBeforeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderAfter [#comparesliderafter]

The container for the "after" content that appears on the right (or bottom in vertical mode).

<AutoTypeTable path="./types/radix/compare-slider.ts" name="CompareSliderAfterProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderHandle [#comparesliderhandle]

The draggable handle that controls the comparison position.

<AutoTypeTable path="./types/radix/compare-slider.ts" name="CompareSliderHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### CompareSliderLabel [#comparesliderlabel]

Custom labels that can be positioned on either side of the comparison.

<AutoTypeTable path="./types/radix/compare-slider.ts" name="CompareSliderLabelProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the slider.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus away from the slider to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves the slider position left (or up in vertical mode) by the step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;, &#x22;ArrowDown&#x22;],
    description: &#x22;Moves the slider position right (or down in vertical mode) by the step amount.&#x22;,
  },
  {
    keys: [&#x22;PageUp&#x22;],
    description: &#x22;Moves the slider position left (or up in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;PageDown&#x22;],
    description: &#x22;Moves the slider position right (or down in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowLeft&#x22;, &#x22;Shift + ArrowUp&#x22;],
    description: &#x22;Moves the slider position left (or up in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowRight&#x22;, &#x22;Shift + ArrowDown&#x22;],
    description: &#x22;Moves the slider position right (or down in vertical mode) by ten steps.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves the slider to the minimum position (0%).&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves the slider to the maximum position (100%).&#x22;,
  },
]"
/>

### Mouse and Touch Interactions [#mouse-and-touch-interactions]

* **Drag**: Click and drag the handle to adjust the comparison position
* **Click**: Click anywhere on the slider container to jump to that position
* **Touch**: Full touch support for mobile devices

## Advanced Usage [#advanced-usage]

### Custom Content Types [#custom-content-types]

The compare slider works with any React content, not just images:

```tsx
<CompareSlider>
  <CompareSliderBefore>
    <div className="flex items-center justify-center bg-blue-500">
      <p>Old Design</p>
    </div>
  </CompareSliderBefore>
  <CompareSliderAfter>
    <div className="flex items-center justify-center bg-green-500">
      <p>New Design</p>
    </div>
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

### Vertical Orientation [#vertical-orientation-1]

Use vertical orientation for comparing content that works better in a vertical layout. The slider handle moves vertically, and the "before" content appears on top while "after" content appears on bottom.

```tsx
<CompareSlider orientation="vertical" className="h-[600px]">
  <CompareSliderBefore>
    {/* Top content */}
  </CompareSliderBefore>
  <CompareSliderAfter>
    {/* Bottom content */}
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

See the [Vertical Orientation example](#vertical-orientation) for a complete demo.

### Custom Labels [#custom-labels]

Add custom labels to identify each side:

```tsx
<CompareSlider>
  <CompareSliderBefore label="Original">
    {/* Content */}
  </CompareSliderBefore>
  <CompareSliderAfter label="Enhanced">
    {/* Content */}
  </CompareSliderAfter>
  <CompareSliderHandle />
</CompareSlider>
```

Or use the `CompareSliderLabel` component for more control:

```tsx
<CompareSlider>
  <CompareSliderBefore>
    {/* Content */}
  </CompareSliderBefore>
  <CompareSliderAfter>
    {/* Content */}
  </CompareSliderAfter>
  <CompareSliderHandle />
  <CompareSliderLabel side="before" className="bg-blue-500/90 text-white">
    Original
  </CompareSliderLabel>
  <CompareSliderLabel side="after" className="bg-green-500/90 text-white">
    Enhanced
  </CompareSliderLabel>
</CompareSlider>
```

## Browser Support [#browser-support]

### Core Features [#core-features]

All core comparison features work in modern browsers:

* **Chrome/Edge**: Full support
* **Firefox**: Full support
* **Safari**: Full support (iOS 13+)

### Touch Gestures [#touch-gestures]

Touch interactions require modern touch APIs:

* **iOS Safari**: Supported from iOS 13+
* **Chrome Mobile**: Full support
* **Firefox Mobile**: Full support

## Troubleshooting [#troubleshooting]

### Content Overflow [#content-overflow]

Ensure your content is properly contained within the slider:

```tsx
<CompareSlider className="h-[400px] overflow-hidden">
  <CompareSliderBefore>
    <img className="size-full object-cover" src="..." />
  </CompareSliderBefore>
  {/* ... */}
</CompareSlider>
```

### Performance with Large Images [#performance-with-large-images]

For large images, consider:

1. Using optimized image formats (WebP, AVIF)
2. Lazy loading images
3. Using appropriate image sizes for the display size
4. Implementing image preloading for smoother transitions

### Mobile Considerations [#mobile-considerations]

On mobile devices:

* Ensure touch targets are adequately sized
* Test on various screen sizes
* Consider using vertical orientation for better mobile UX
* Ensure content is responsive and scales appropriately

## Credits [#credits]

* [Samuel Ferrara](https://unsplash.com/@samferrara?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/photos/aerial-photo-of-foggy-mountains-1527pjeb6jg?utm_source=unsplash\&utm_medium=referral\&utm_content=creditCopyText) - For the demo images used in the examples.


# Cropper
URL: /docs/components/radix/cropper



<ComponentTabs name="cropper-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/cropper

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="cropper" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Cropper,
  CropperArea,
  CropperImage,
  CropperVideo,
} from "@/components/ui/cropper";

return (
  <Cropper>
    <CropperImage src="/image.jpg" alt="Image to crop" />
    <CropperArea />
  </Cropper>
)
```

## Examples [#examples]

### Controlled State [#controlled-state]

A cropper with external controls for zoom, rotation, and crop position.

<ComponentTabs name="cropper-controlled-demo" />

### With File Upload [#with-file-upload]

A cropper integrated with the [FileUpload](https://diceui.com/docs/components/radix/file-upload) component for uploading and cropping images.

<ComponentTabs name="cropper-file-upload-demo" />

### Different Shapes [#different-shapes]

A cropper with different shapes and configuration options.

<ComponentTabs name="cropper-shapes-demo" />

### Video Cropping [#video-cropping]

A cropper that works with video content.

<ComponentTabs name="cropper-video-demo" />

## API Reference [#api-reference]

### Cropper [#cropper]

The root container for the cropper component.

<AutoTypeTable path="./types/radix/cropper.ts" name="CropperProps" />

### CropperImage [#cropperimage]

The image element to be cropped.

<AutoTypeTable path="./types/radix/cropper.ts" name="CropperImageProps" />

### CropperVideo [#croppervideo]

The video element to be cropped.

<AutoTypeTable path="./types/radix/cropper.ts" name="CropperVideoProps" />

### CropperArea [#cropperarea]

The crop area overlay that shows the selected region.

<AutoTypeTable path="./types/radix/cropper.ts" name="CropperAreaProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the cropper content.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves the crop area up by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves the crop area down by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves the crop area left by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves the crop area right by the keyboard step amount.&#x22;,
  },
  {
    keys: [&#x22;Shift + Arrow Keys&#x22;],
    description: &#x22;Moves the crop area with finer precision (20% of keyboard step).&#x22;,
  },
]"
/>

### Mouse and Touch Interactions [#mouse-and-touch-interactions]

* **Drag**: Pan the media within the crop area
* **Scroll/Wheel**: Zoom in and out (can be disabled with `preventScrollZoom`)
* **Pinch**: Zoom and rotate on touch devices
* **Two-finger drag**: Pan while maintaining pinch zoom

## Advanced Usage [#advanced-usage]

### Custom Crop Calculations [#custom-crop-calculations]

You can use the crop data from `onCropComplete` to perform server-side cropping:

```tsx
const onCropComplete = (croppedArea, croppedAreaPixels) => {
  // croppedArea contains percentages (0-100)
  // croppedAreaPixels contains actual pixel coordinates
  
  // Send to server for processing
  cropImage({
    x: croppedAreaPixels.x,
    y: croppedAreaPixels.y,
    width: croppedAreaPixels.width,
    height: croppedAreaPixels.height,
  });
};
```

### Performance Optimization [#performance-optimization]

The cropper includes several performance optimizations:

* **LRU Caching**: Frequently used calculations are cached
* **RAF Throttling**: UI updates are throttled using requestAnimationFrame
* **Quantization**: Values are quantized to reduce cache misses
* **Lazy Computation**: Expensive calculations are deferred when possible

### Object Fit Modes [#object-fit-modes]

The cropper supports different object fit modes:

* **contain**: Media fits entirely within the container (default)
* **cover**: Media covers the entire container, may be cropped
* **horizontal-cover**: Media width matches container width
* **vertical-cover**: Media height matches container height

## Browser Support [#browser-support]

### Core Features [#core-features]

All core cropping features work in modern browsers:

* **Chrome/Edge**: Full support
* **Firefox**: Full support
* **Safari**: Full support (iOS 13+)

### Touch Gestures [#touch-gestures]

Multi-touch gestures require modern touch APIs:

* **iOS Safari**: Supported from iOS 13+
* **Chrome Mobile**: Full support
* **Firefox Mobile**: Basic touch support

### Video Support [#video-support]

Video cropping requires modern video APIs:

* **Chrome/Edge**: Full support for all video formats
* **Firefox**: Full support with some codec limitations
* **Safari**: Full support with H.264/HEVC

## Troubleshooting [#troubleshooting]

### CORS Issues [#cors-issues]

When cropping images from external domains, ensure proper CORS headers:

```tsx
<CropperImage
  src="https://example.com/image.jpg"
  crossOrigin="anonymous"
  alt="External image"
/>
```

### Performance with Large Media [#performance-with-large-media]

For large images or videos, consider:

1. Pre-processing media to reasonable sizes
2. Using `snapPixels` for crisp rendering
3. Limiting zoom range with `minZoom` and `maxZoom`
4. Reducing `keyboardStep` for smoother interactions

### Mobile Considerations [#mobile-considerations]

On mobile devices:

* Use appropriate viewport meta tags
* Consider touch target sizes for controls
* Test pinch-to-zoom interactions
* Ensure adequate spacing around interactive elements

## Credits [#credits]

* [Unsplash](https://unsplash.com/) - For the photos used in examples.
* [Blender Foundation](https://www.blender.org/) - For the video used in examples.


# Data Grid
URL: /docs/components/radix/data-grid



<ComponentTabs name="data-grid-demo" />

## Installation [#installation]

<Steps>
  <Step>
    Install the main component and dependencies:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>

  <Step>
    Install the following optional components:

    [`getDataGridSelectColumn`](#getdatagridselectcolumn):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-select-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`getDataGridActionsColumn`](#getdatagridactionscolumn):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-actions-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridSortMenu`](#datagridsortmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-sort-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridFilterMenu`](#datagridfiltermenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-filter-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridRowHeightMenu`](#datagridrowheightmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-row-height-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridViewMenu`](#datagridviewmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-view-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridKeyboardShortcuts`](#datagridkeyboardshortcuts):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-keyboard-shortcuts"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataGridSkeleton`](#datagridskeleton):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-grid-skeleton"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`useDataGridUndoRedo`](#usedatagridundoredo):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/use-data-grid-undo-redo"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>
</Steps>

## Usage [#usage]

### Basic Data Grid [#basic-data-grid]

```tsx
import { DataGrid } from "@/components/data-grid/data-grid";
import { DataGridKeyboardShortcuts } from "@/components/data-grid/data-grid-keyboard-shortcuts";
import { useDataGrid } from "@/hooks/use-data-grid";

export default function MyDataGrid() {
  const [data, setData] = React.useState(initialData);
  
  const columns = React.useMemo(() => [
    {
      id: "name",
      accessorKey: "name",
      header: "Name",
      meta: {
        cell: {
          variant: "short-text",
        },
      },
    },
    // ... other columns
  ], []);

  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
    onDataChange: setData,
    getRowId: (row) => row.id,
  });

  return (
    <>
      <DataGridKeyboardShortcuts />
      <DataGrid table={table} {...dataGridProps} />
    </>
  );
}
```

### With Toolbar Menus [#with-toolbar-menus]

Add sort, filter, row height, and view menus:

```tsx
import { DataGrid } from "@/components/data-grid/data-grid";
import { DataGridFilterMenu } from "@/components/data-grid/data-grid-filter-menu";
import { DataGridKeyboardShortcuts } from "@/components/data-grid/data-grid-keyboard-shortcuts";
import { DataGridRowHeightMenu } from "@/components/data-grid/data-grid-row-height-menu";
import { DataGridSortMenu } from "@/components/data-grid/data-grid-sort-menu";
import { DataGridViewMenu } from "@/components/data-grid/data-grid-view-menu";
import { useDataGrid } from "@/hooks/use-data-grid";

export default function DataGridToolbarDemo() {
  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
    onDataChange: setData,
  });

  return (
    <div className="flex flex-col gap-4">
      {/* Toolbar */}
      <div role="toolbar" aria-orientation="horizontal" className="flex items-center gap-2 self-end">
        <DataGridFilterMenu table={table} />
        <DataGridSortMenu table={table} />
        <DataGridRowHeightMenu table={table} />
        <DataGridViewMenu table={table} />
      </div>
      
      <DataGridKeyboardShortcuts />
      <DataGrid table={table} {...dataGridProps} />
    </div>
  );
}
```

### With Row Management [#with-row-management]

Add and delete rows with callbacks:

```tsx
const onRowAdd = React.useCallback(() => {
  const newRow = { id: generateId() };
  setData((prev) => [...prev, newRow]);
  
  return {
    rowId: newRow.id,
    columnId: "name", // Focus this column after creating the new row
  };
}, []);

const onRowsDelete = React.useCallback((rows, rowIds) => {
  // rows: array of row data objects
  // rowIds: array of row ids
  setData((prev) => prev.filter((row) => !rows.includes(row)));
}, []);

const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  onRowAdd,
  onRowsDelete,
  getRowId: (row) => row.id,
});
```

### With Search [#with-search]

Use the `enableSearch` prop to enable search functionality:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  enableSearch: true, // Enable search (Ctrl/Cmd+F)
});

return (
  <>
    <DataGridKeyboardShortcuts enableSearch />
    <DataGrid {...dataGridProps} table={table} />
  </>
);
```

### With Paste Support [#with-paste-support]

Use the `enablePaste` prop to enable pasting from clipboard:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onDataChange: setData,
  enablePaste: true, // Enable paste (Ctrl/Cmd+V)
  onRowsAdd: async (count) => {
    // Called when paste needs to add new rows
    // This is more performant than adding rows one by one with the `onRowAdd` prop
    const newRows = Array.from({ length: count }, () => ({ id: generateId() }));
    setData((prev) => [...prev, ...newRows]);
  },
});
```

### With Undo/Redo [#with-undoredo]

Use the `useDataGridUndoRedo` hook to add undo/redo support with keyboard shortcuts (Ctrl/Cmd+Z to undo, Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y to redo):

```tsx
import { useDataGrid } from "@/hooks/use-data-grid";
import {
  useDataGridUndoRedo,
  type UndoRedoCellUpdate,
} from "@/hooks/use-data-grid-undo-redo";

export default function MyDataGrid() {
  const [data, setData] = React.useState(initialData);

  const { trackCellsUpdate, trackRowsAdd, trackRowsDelete } =
    useDataGridUndoRedo({
      data,
      onDataChange: setData,
      getRowId: (row) => row.id,
    });

  const onDataChange = React.useCallback(
    (newData: Person[]) => {
      // Track cell updates for undo/redo
      const cellUpdates: Array<UndoRedoCellUpdate> = [];

      for (let rowIndex = 0; rowIndex < data.length; rowIndex++) {
        const oldRow = data[rowIndex];
        const newRow = newData[rowIndex];
        if (!oldRow || !newRow) continue;

        for (const key of Object.keys(oldRow)) {
          const oldValue = oldRow[key];
          const newValue = newRow[key];
          if (!Object.is(oldValue, newValue)) {
            cellUpdates.push({
              rowId: oldRow.id,
              columnId: key,
              previousValue: oldValue,
              newValue,
            });
          }
        }
      }

      if (cellUpdates.length > 0) {
        trackCellsUpdate(cellUpdates);
      }

      setData(newData);
    },
    [data, trackCellsUpdate],
  );

  const onRowAdd = React.useCallback(() => {
    const newRow = { id: generateId() };
    setData((prev) => [...prev, newRow]);
    trackRowsAdd([newRow]);
    return { rowId: newRow.id, columnId: "name" };
  }, [trackRowsAdd]);

  const onRowsDelete = React.useCallback(
    (rows) => {
      trackRowsDelete(rows);
      setData((prev) => prev.filter((row) => !rows.includes(row)));
    },
    [trackRowsDelete],
  );

  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
    onDataChange,
    onRowAdd,
    onRowsDelete,
    getRowId: (row) => row.id,
  });

  return (
    <>
      <DataGridKeyboardShortcuts enableUndoRedo />
      <DataGrid table={table} {...dataGridProps} />
    </>
  );
}
```

### Read-Only Mode [#read-only-mode]

Use the `readOnly` prop to make the grid read-only:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  readOnly: true, // Disable all editing
});
```

### RTL Support [#rtl-support]

Wrap the grid in a `DirectionProvider` and the language direction will be automatically detected. The `direction` component is included when you install the data grid — see the [shadcn Direction docs](https://ui.shadcn.com/docs/components/radix/direction) for the underlying API.

```tsx
import { DirectionProvider } from "@/components/ui/direction";

return (
  <DirectionProvider dir="rtl">
    <DataGridImpl />
  </DirectionProvider>
)

function DataGridImpl() {
  const { table, ...dataGridProps } = useDataGrid({
    data,
    columns,
  });

  return (
    <DataGrid table={table} {...dataGridProps} />
  )
}
```

### Auto Focus [#auto-focus]

Use the `autoFocus` prop to automatically focus any navigable cell on mount:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  autoFocus: true, // Focus first navigable cell
  // Or focus a specific cell:
  // autoFocus: { rowId: "row-1", columnId: "name" },
});
```

### Custom Height and Stretch Columns [#custom-height-and-stretch-columns]

Control the grid height and column stretching:

```tsx
<DataGrid 
  table={table} 
  {...dataGridProps} 
  height={800} // Custom height in pixels (default: 600)
  stretchColumns={true} // Stretch columns to fill available width
/>
```

### Loading States [#loading-states]

Use the `DataGridSkeleton` component for loading states:

```tsx
import { Suspense } from "react";
import {
  DataGridSkeleton,
  DataGridSkeletonGrid,
  DataGridSkeletonToolbar,
} from "@/components/data-grid/data-grid-skeleton";

export default function Page() {
  return (
    <Suspense
      fallback={
        <DataGridSkeleton className="container flex flex-col gap-4 py-4">
          <DataGridSkeletonToolbar actionCount={5} />
          <DataGridSkeletonGrid />
        </DataGridSkeleton>
      }
    >
      <DataGridDemo />
    </Suspense>
  );
}
```

## Cell Variants [#cell-variants]

The Data Grid supports various cell variants for different data formats:

### Short Text Cell [#short-text-cell]

Single-line text input with inline editing:

```tsx
{
  id: "name",
  accessorKey: "name",
  header: "Name",
  meta: {
    cell: {
      variant: "short-text",
    },
  },
}
```

### Long Text Cell [#long-text-cell]

Multi-line text displayed in a popover with auto-save:

```tsx
{
  id: "notes",
  accessorKey: "notes",
  header: "Notes",
  meta: {
    cell: {
      variant: "long-text",
    },
  },
}
```

### Number Cell [#number-cell]

Numeric input with optional constraints:

```tsx
{
  id: "price",
  accessorKey: "price",
  header: "Price",
  meta: {
    cell: {
      variant: "number",
      min: 0,
      max: 1000,
      step: 0.01,
    },
  },
}
```

### URL Cell [#url-cell]

URL input with validation and clickable links:

```tsx
{
  id: "website",
  accessorKey: "website",
  header: "Website",
  meta: {
    cell: {
      variant: "url",
    },
  },
}
```

### Checkbox Cell [#checkbox-cell]

Boolean checkbox for true/false values:

```tsx
{
  id: "isActive",
  accessorKey: "isActive",
  header: "Active",
  meta: {
    cell: {
      variant: "checkbox",
    },
  },
}
```

### Select Cell [#select-cell]

Single-select input with predefined options:

```tsx
{
  id: "category",
  accessorKey: "category",
  header: "Category",
  meta: {
    cell: {
      variant: "select",
      options: [
        { label: "Electronics", value: "electronics" },
        { label: "Clothing", value: "clothing" },
        { label: "Books", value: "books" },
      ],
    },
  },
}
```

### Multi-Select Cell [#multi-select-cell]

Multi-select input with predefined options and badge display:

```tsx
{
  id: "skills",
  accessorKey: "skills",
  header: "Skills",
  meta: {
    cell: {
      variant: "multi-select",
      options: [
        { label: "JavaScript", value: "javascript" },
        { label: "TypeScript", value: "typescript" },
        { label: "React", value: "react" },
      ],
    },
  },
}
```

### Date Cell [#date-cell]

Date picker with calendar popover:

```tsx
{
  id: "startDate",
  accessorKey: "startDate",
  header: "Start Date",
  meta: {
    cell: {
      variant: "date",
    },
  },
}
```

### File Cell [#file-cell]

File upload with support for multiple files and file management:

```tsx
{
  id: "attachments",
  accessorKey: "attachments",
  header: "Attachments",
  meta: {
    cell: {
      variant: "file",
      maxFileSize: 10 * 1024 * 1024, // 10MB
      maxFiles: 5,
      accept: "image/*,video/*,audio/*,.pdf,.doc,.docx",
      multiple: true,
    },
  },
}
```

To use file cells, provide upload and delete handlers:

```tsx
const onFilesUpload = React.useCallback(async ({ files, rowId, columnId }) => {
  // Upload files to your server/storage
  const formData = new FormData();
  files.forEach(file => formData.append('files', file));
  
  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData
  });
  
  const data = await response.json();
  
  // Return array of file metadata
  return data.files.map(f => ({
    id: f.fileId,
    name: f.fileName,
    size: f.fileSize,
    type: f.fileType,
    url: f.fileUrl
  }));
}, []);

const onFilesDelete = React.useCallback(async ({ fileIds, rowId, columnId }) => {
  // Delete files from your server/storage
  await fetch('/api/files', {
    method: 'DELETE',
    body: JSON.stringify({ fileIds })
  });
}, []);

const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  onFilesUpload,
  onFilesDelete,
});
```

## Row Selection [#row-selection]

Add a selection column to enable row selection with shift-click support using the `getDataGridSelectColumn` helper:

```tsx
import { getDataGridSelectColumn } from "@/components/data-grid/data-grid-select-column";

const columns = [
  getDataGridSelectColumn<YourData>(),
  // ... other columns
];
```

You can customize the select column by passing options:

```tsx
getDataGridSelectColumn<YourData>({
  size: 50, // Custom width (default: 40)
  enableHiding: true, // Allow hiding via view menu (default: false)
  enableResizing: true, // Allow resizing (default: false)
})
```

The shift-click functionality is handled automatically by the `useDataGrid` hook when you include the select column.

## Row Actions [#row-actions]

Add a menu of actions to each row with `getDataGridActionsColumn`, and show bulk actions for the selection with the `actionBar` prop. The action bar renders while rows or a range of cells are selected.

```tsx
import { getDataGridActionsColumn } from "@/components/data-grid/data-grid-actions-column";
import { getDataGridSelectColumn } from "@/components/data-grid/data-grid-select-column";
import { DropdownMenuItem } from "@/components/ui/dropdown-menu";

const columns = React.useMemo(() => [
  getDataGridSelectColumn(),
  // ... other columns
  getDataGridActionsColumn({
    actions: ({ row }) => (
      <DropdownMenuItem onClick={() => onRowDelete(row.original)}>
        Delete
      </DropdownMenuItem>
    ),
  }),
], [onRowDelete]);

const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  initialState: {
    columnPinning: { start: ["select"], end: ["actions"] },
  },
});

return (
  <DataGrid
    {...dataGridProps}
    table={table}
    actionBar={<TasksActionBar table={table} />}
  />
);
```

## Cell Architecture [#cell-architecture]

The Data Grid uses a three-layer cell composition pattern:

1. **DataGridCell**: Routes to the appropriate cell variant based on the column's `meta.cell.variant` property
2. **Cell Variants**: Implement specific editing UIs for different data variants (text, number, select, etc.)
3. **DataGridCellWrapper**: Provides common functionality for all cells (focus, selection, keyboard interactions)

```tsx
// Cell composition flow
<DataGridCell {...cellProps} />
  ↓
<ShortTextCell {...props} />  // Based on variant
  ↓
<DataGridCellWrapper {...props}>
  {/* Cell-specific content */}
</DataGridCellWrapper>
```

Each cell variant receives the same props and wraps its content in `DataGridCellWrapper`, which provides:

* Focus management and visual focus ring
* Selection state and highlighting
* Search match highlighting
* Click, double-click, and keyboard event management
* Edit mode triggering (Enter, F2, Space, or typing)

### Creating Custom Cell Variants [#creating-custom-cell-variants]

You can create custom cell variants by implementing the `DataGridCellProps` interface and wrapping your content in `DataGridCellWrapper`:

```tsx
import { DataGridCellWrapper } from "@/components/data-grid/data-grid-cell-wrapper";
import type { DataGridCellProps } from "@/lib/data-grid-types";

export function CustomCell<TData>(props: DataGridCellProps<TData>) {
  const { cell, isEditing, readOnly } = props;
  const value = cell.getValue() as CustomCellValue;

  function onCommit(nextValue: CustomCellValue) {
    if (!readOnly) cell.setValue(nextValue);
    cell.table.stopEditing();
  }

  return (
    <DataGridCellWrapper {...props}>
      {/* Your custom cell content */}
    </DataGridCellWrapper>
  );
}
```

Cells read and write data through the cell, with `cell.getValue()` and `cell.setValue()`, and control edit mode with `cell.startEditing()` and `cell.table.stopEditing()`.

## Column Configuration [#column-configuration]

### Enabling Filtering and Sorting [#enabling-filtering-and-sorting]

To enable filtering and sorting on columns, use the `filterFn` from the data grid library:

```tsx
import { getFilterFn } from "@/lib/data-grid-filters";

const columns = React.useMemo(() => {
  const filterFn = getFilterFn<YourData>();
  
  return [
    {
      id: "name",
      accessorKey: "name",
      header: "Name",
      filterFn, // Enable filtering
      // Sorting is enabled by default
      meta: {
        label: "Name", // Label shown in filter/sort menus
        cell: {
          variant: "short-text",
        },
      },
    },
    // ... other columns
  ];
}, []);
```

### Column Pinning [#column-pinning]

Pin columns to the left or right:

```tsx
const { table, ...dataGridProps } = useDataGrid({
  data,
  columns,
  initialState: {
    columnPinning: {
      start: ["select", "name"], // Pin to the start side
      end: ["actions"], // Pin to the end side
    },
  },
});
```

You can also pin/unpin columns dynamically via the column header dropdown menu.

### Column Resizing [#column-resizing]

Column resizing is enabled by default. Users can:

* Drag the column resize handle
* Double-click the resize handle to auto-fit the column width

Set minimum column size using `minSize`:

```tsx
{
  id: "name",
  accessorKey: "name",
  header: "Name",
  minSize: 180, // Minimum width in pixels
  meta: {
    cell: {
      variant: "short-text",
    },
  },
}
```

## Context Menu Actions [#context-menu-actions]

Right-click on cells to access context menu options:

* **Copy** (Ctrl/Cmd+C): Copy selected cells to clipboard
* **Cut** (Ctrl/Cmd+X): Cut selected cells (shows visual indicator)
* **Clear** (Delete/Backspace): Clear content from selected cells
* **Delete rows** (Ctrl/Cmd+Backspace): Remove selected rows (only available when `onRowsDelete` is provided)

## API Reference [#api-reference]

### useDataGrid [#usedatagrid]

Hook for initializing the data grid with state management and editing capabilities.

<AutoTypeTable path="./types/radix/data-grid.ts" name="UseDataGridProps" />

### useDataGridUndoRedo [#usedatagridundoredo]

Hook for adding undo/redo support to the data grid with keyboard shortcuts and history management.

<AutoTypeTable path="./types/radix/data-grid.ts" name="UseDataGridUndoRedoProps" />

Returns:

<AutoTypeTable path="./types/radix/data-grid.ts" name="UseDataGridUndoRedoReturn" />

### DataGrid [#datagrid]

Main data grid component with virtualization and editing capabilities.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridProps" />

### getDataGridSelectColumn [#getdatagridselectcolumn]

A utility function that returns a reusable select column definition for the data grid with checkbox selection and shift-click support.

<AutoTypeTable path="./types/radix/data-grid.ts" name="GetDataGridSelectColumnProps" />

### getDataGridActionsColumn [#getdatagridactionscolumn]

A utility function that returns an actions column with a dropdown menu for each row.

<AutoTypeTable path="./types/radix/data-grid.ts" name="GetDataGridActionsColumnProps" />

### DataGridColumnHeader [#datagridcolumnheader]

Column header with sorting controls and visual indicators for sort direction.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridColumnHeaderProps" />

### DataGridCell [#datagridcell]

Routes to the appropriate cell variant based on the column's `meta.cell.variant` property.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridCellProps" />

### DataGridCellWrapper [#datagridcellwrapper]

Base wrapper providing common functionality for all cell variants including focus management, selection state, search highlighting, and keyboard interactions.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridCellWrapperProps" />

### DataGridCellVariants [#datagridcellvariants]

Individual cell variants for different data variants. Each variant implements the `DataGridCellProps` interface and wraps its content in `DataGridCellWrapper`.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridCellProps" />

Available cell variants:

* **ShortTextCell**: Single-line text input with inline contentEditable
* **LongTextCell**: Multi-line textarea displayed in a popover dialog with auto-save
* **NumberCell**: Numeric input with optional min, max, and step constraints
* **UrlCell**: URL input with validation and clickable links
* **SelectCell**: Single-select dropdown with predefined options
* **MultiSelectCell**: Multi-select input with badge display and command palette
* **CheckboxCell**: Boolean checkbox for true/false values
* **DateCell**: Date picker with calendar popover
* **FileCell**: File upload with support for multiple files and file management

### DataGridRow [#datagridrow]

Individual row component with virtualization support for large datasets.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridRowProps" />

### DataGridSearch [#datagridsearch]

Search menu with keyboard shortcuts for finding and navigating between matching cells in the grid.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridSearchProps" />

### DataGridFilterMenu [#datagridfiltermenu]

Filter menu with drag-and-drop reordering and advanced filtering operators for text, number, date, select, and boolean fields.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridFilterMenuProps" />

### DataGridSortMenu [#datagridsortmenu]

Sort menu with drag-and-drop reordering for multi-column sorting with ascending/descending controls.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridSortMenuProps" />

### DataGridRowHeightMenu [#datagridrowheightmenu]

Row height menu for adjusting row sizes between short, medium, tall, and extra-tall options.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridRowHeightMenuProps" />

### DataGridViewMenu [#datagridviewmenu]

View menu for controlling column visibility with search functionality.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridViewMenuProps" />

### DataGridContextMenu [#datagridcontextmenu]

Right-click context menu for quick access to common cell and row actions like copy, cut, clear, and delete.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridContextMenuProps" />

### DataGridPasteDialog [#datagridpastedialog]

Dialog for handling paste operations that require adding new rows to the grid.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridPasteDialogProps" />

### DataGridKeyboardShortcuts [#datagridkeyboardshortcuts]

Searchable reference dialog for all available keyboard shortcuts for navigating and interacting with the data grid.

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridKeyboardShortcutsProps" />

### DataGridSkeleton [#datagridskeleton]

A composable skeleton component for the data grid with toolbar and grid parts for loading states.

```tsx
import {
  DataGridSkeleton,
  DataGridSkeletonGrid,
  DataGridSkeletonToolbar,
} from "@/components/data-grid/data-grid-skeleton";

return (
  <DataGridSkeleton>
    <DataGridSkeletonToolbar />
    <DataGridSkeletonGrid />
  </DataGridSkeleton>
);
```

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridSkeletonProps" />

#### DataGridSkeletonToolbar [#datagridskeletontoolbar]

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridSkeletonToolbarProps" />

#### DataGridSkeletonGrid [#datagridskeletongrid]

<AutoTypeTable path="./types/radix/data-grid.ts" name="DataGridSkeletonGridProps" />

## Accessibility [#accessibility]

The Data Grid follows WAI-ARIA guidelines for grid widgets:

* Full keyboard navigation support
* Proper ARIA labels, roles, and properties
* Focus management with visible focus indicators
* Keyboard shortcuts for all actions
* Screen reader friendly cell updates

## Keyboard Interactions [#keyboard-interactions]

### Navigation [#navigation]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;↑&#x22;, &#x22;↓&#x22;, &#x22;←&#x22;, &#x22;→&#x22;],
    description: &#x22;Navigate between cells&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Move to next cell&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Move to previous cell&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Move to first column&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Move to last column&#x22;,
  },
  {
    keys: [&#x22;Ctrl + ↑&#x22;, &#x22;Cmd + ↑&#x22;],
    description: &#x22;Move to first row (same column)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + ↓&#x22;, &#x22;Cmd + ↓&#x22;],
    description: &#x22;Move to last row (same column)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + ←&#x22;, &#x22;Cmd + ←&#x22;],
    description: &#x22;Move to first column (same row)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + →&#x22;, &#x22;Cmd + →&#x22;],
    description: &#x22;Move to last column (same row)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Home&#x22;, &#x22;Cmd + Home&#x22;],
    description: &#x22;Move to first cell&#x22;,
  },
  {
    keys: [&#x22;Ctrl + End&#x22;, &#x22;Cmd + End&#x22;],
    description: &#x22;Move to last cell&#x22;,
  },
  {
    keys: [&#x22;PgUp&#x22;],
    description: &#x22;Move up one page&#x22;,
  },
  {
    keys: [&#x22;PgDn&#x22;],
    description: &#x22;Move down one page&#x22;,
  },
  {
    keys: [&#x22;Alt + ↑&#x22;],
    description: &#x22;Scroll up one page&#x22;,
  },
  {
    keys: [&#x22;Alt + ↓&#x22;],
    description: &#x22;Scroll down one page&#x22;,
  },
  {
    keys: [&#x22;Alt + PgUp&#x22;],
    description: &#x22;Scroll left one page of columns&#x22;,
  },
  {
    keys: [&#x22;Alt + PgDn&#x22;],
    description: &#x22;Scroll right one page of columns&#x22;,
  },
]"
/>

### Selection [#selection]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Shift + ↑&#x22;, &#x22;Shift + ↓&#x22;, &#x22;Shift + ←&#x22;, &#x22;Shift + →&#x22;],
    description: &#x22;Extend selection&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + ↑&#x22;, &#x22;Cmd + Shift + ↑&#x22;],
    description: &#x22;Select to top of table&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + ↓&#x22;, &#x22;Cmd + Shift + ↓&#x22;],
    description: &#x22;Select to bottom of table&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + ←&#x22;, &#x22;Cmd + Shift + ←&#x22;],
    description: &#x22;Select to first column&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + →&#x22;, &#x22;Cmd + Shift + →&#x22;],
    description: &#x22;Select to last column&#x22;,
  },
  {
    keys: [&#x22;Ctrl + A&#x22;, &#x22;Cmd + A&#x22;],
    description: &#x22;Select all cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Click&#x22;, &#x22;Cmd + Click&#x22;],
    description: &#x22;Toggle cell selection&#x22;,
  },
  {
    keys: [&#x22;Shift + Click&#x22;],
    description: &#x22;Select range&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Clear selection or exit edit mode&#x22;,
  },
]"
/>

### Editing [#editing]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Start editing cell&#x22;,
  },
  {
    keys: [&#x22;F2&#x22;],
    description: &#x22;Start editing cell&#x22;,
  },
  {
    keys: [&#x22;Double Click&#x22;],
    description: &#x22;Start editing cell&#x22;,
  },
  {
    keys: [&#x22;Shift + Enter&#x22;],
    description: &#x22;Insert row below&#x22;,
  },
  {
    keys: [&#x22;Ctrl + C&#x22;, &#x22;Cmd + C&#x22;],
    description: &#x22;Copy selected cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + X&#x22;, &#x22;Cmd + X&#x22;],
    description: &#x22;Cut selected cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + V&#x22;, &#x22;Cmd + V&#x22;],
    description: &#x22;Paste cells&#x22;,
  },
  {
    keys: [&#x22;Delete&#x22;],
    description: &#x22;Clear selected cells&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;Clear selected cells&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Backspace&#x22;, &#x22;Cmd + Backspace&#x22;],
    description: &#x22;Delete selected rows&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Delete&#x22;, &#x22;Cmd + Delete&#x22;],
    description: &#x22;Delete selected rows&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Z&#x22;, &#x22;Cmd + Z&#x22;],
    description: &#x22;Undo last action&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + Z&#x22;, &#x22;Cmd + Shift + Z&#x22;],
    description: &#x22;Redo last action&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Y&#x22;, &#x22;Cmd + Y&#x22;],
    description: &#x22;Redo last action&#x22;,
  },
]"
/>

### Search & Shortcuts [#search--shortcuts]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Ctrl + F&#x22;, &#x22;Cmd + F&#x22;],
    description: &#x22;Open search&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Next search match (when search is open)&#x22;,
  },
  {
    keys: [&#x22;Shift + Enter&#x22;],
    description: &#x22;Previous search match (when search is open)&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Close search (when search is open)&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + F&#x22;, &#x22;Cmd + Shift + F&#x22;],
    description: &#x22;Toggle filter menu&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + S&#x22;, &#x22;Cmd + Shift + S&#x22;],
    description: &#x22;Toggle sort menu&#x22;,
  },
  {
    keys: [&#x22;Ctrl + /&#x22;, &#x22;Cmd + /&#x22;],
    description: &#x22;Show keyboard shortcuts&#x22;,
  },
]"
/>

## Features [#features]

The Data Grid component provides a comprehensive spreadsheet-like experience with:

### Core Features [#core-features]

* **High Performance**: Virtualized rows and columns for handling large datasets (10,000+ rows)
* **Cell Editing**: In-place editing with 9 different cell variants
* **Cell Selection**: Single and multi-cell selection with keyboard and mouse
* **Keyboard Navigation**: Full keyboard support with Excel-like shortcuts
* **Copy/Cut/Paste**: Full clipboard support including paste from Excel/Google Sheets
* **Undo/Redo**: Full history support for cell updates, row additions, and deletions (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z)
* **Context Menu**: Right-click actions for cells and rows
* **Search**: Find and navigate to matching cells (Ctrl/Cmd+F)
* **Filtering**: Advanced filtering with multiple operators and drag-and-drop reordering
* **Sorting**: Multi-column sorting with drag-and-drop reordering
* **Row Management**: Add and delete rows with callbacks
* **Column Features**: Resizing, pinning (left/right), hiding, and reordering

### Cell Variants [#cell-variants-1]

* **Text Cells**: Short-text and long-text with auto-save
* **Number Cells**: With min/max/step constraints
* **URL Cells**: With validation and clickable links
* **Date Cells**: Calendar picker with keyboard navigation
* **Select Cells**: Single and multi-select with search
* **Checkbox Cells**: Boolean values
* **File Cells**: Upload and manage multiple files per cell

### Advanced Features [#advanced-features]

* **Smart Paste**: Automatically expands grid when pasting more data than fits
* **Auto-Fill**: Type to start editing, like in Excel
* **Row Heights**: Adjustable row heights (short, medium, tall, extra-tall)
* **RTL Support**: Full right-to-left language support
* **Read-Only Mode**: Lock the grid to prevent editing
* **Auto-Focus**: Focus specific cell on mount
* **Accessibility**: Full ARIA support and keyboard navigation

## Credits [#credits]

* [TanStack Table](https://tanstack.com/table) - For the table state management.
* [TanStack Virtual](https://tanstack.com/virtual) - For the virtualization.
* [shadcn/ui](https://ui.shadcn.com) - For the UI components.
* [Airtable](https://www.airtable.com) and [Glide Data Grid](https://grid.glideapps.com/) - For accessibility and best practices.


# Data Table
URL: /docs/components/radix/data-table



<ComponentTabs name="data-table-demo" className="p-4" />

## Installation [#installation]

<Steps>
  <Step>
    Install the main component and dependencies:

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Filter and sort menu installs bundle a `sortable` component that uses the unified [`radix-ui`](https://www.radix-ui.com/primitives/docs/overview/getting-started) package. Individual `@radix-ui/react-*` packages (such as `@radix-ui/react-slot`) are no longer required.
  </Step>

  <Step>
    Wrap your application with the [`NuqsAdapter`](https://nuqs.47ng.com/docs/adapters) for query state management:

    ```tsx
    import { NuqsAdapter } from "nuqs/adapters/next/app";

    <NuqsAdapter>
      <App />
    </NuqsAdapter>
    ```
  </Step>

  <Step>
    Install the following optional components:

    [`DataTableSortMenu`](#datatablesortmenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-sort-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataTableFilterMenu`](#datatablefiltermenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-filter-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`DataTableCommandFilterMenu`](#datatablecommandfiltermenu):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-command-filter-menu"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`getDataTableSelectColumn`](#row-selection):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-select-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    [`getDataTableActionsColumn`](#row-actions):

    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add "@diceui/data-table-actions-column"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Step>
</Steps>

## Layout [#layout]

Import the components and compose them together:

```tsx
import { DataTable } from "@/components/data-table/data-table";
import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";
import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
import { useDataTable } from "@/hooks/use-data-table";

const { table } = useDataTable({
  data,
  columns,
  pageCount,
});

return (
  <DataTable table={table}>
    <DataTableToolbar table={table}>
      <DataTableSortMenu table={table} />
    </DataTableToolbar>
  </DataTable>
);
```

For the advanced toolbar with a filter menu, swap the toolbar:

```tsx
import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu";

return (
  <DataTable table={table}>
    <DataTableAdvancedToolbar table={table}>
      <DataTableFilterMenu table={table} />
      <DataTableSortMenu table={table} />
    </DataTableAdvancedToolbar>
  </DataTable>
);
```

## Walkthrough [#walkthrough]

<Steps>
  <Step>
    Define columns with appropriate metadata:

    ```tsx
    import { Text, CalendarIcon, DollarSign } from "lucide-react";
    import { DataTableColumnHeader } from "@/components/data-table/data-table-column-header";

    const columns = React.useMemo(() => [
      {
        // Provide an unique id for the column
        // This id will be used as query key for the column filter
        id: "title", // [!code highlight]
        accessorKey: "title",
        header: ({ column }) => (
          <DataTableColumnHeader column={column} label="Title" />
        ),
        cell: ({ row }) => <div>{row.getValue("title")}</div>,
        // Define the column meta options for sorting, filtering, and view options
        meta: { // [!code highlight]
          label: "Title", // [!code highlight]
          placeholder: "Search titles...", // [!code highlight]
          variant: "text", // [!code highlight]
          icon: Text, // [!code highlight]
        }, // [!code highlight] 
        // By default, the column will not be filtered. Set to `true` to enable filtering.
        enableColumnFilter: true, // [!code highlight]
      },
    ], []);
    ```
  </Step>

  <Step>
    Initialize the table state using the `useDataTable` hook:

    ```tsx
    import { useDataTable } from "@/hooks/use-data-table";

    function DataTableDemo() {
      const { table } = useDataTable({
        data,
        columns,
        // Pass the total number of pages for server-side data,
        // or set `mode: "client"` to sort, filter, and paginate in the browser
        pageCount, // [!code highlight]
        initialState: {
          sorting: [{ id: "createdAt", desc: true }],
          pagination: { pageSize: 10 },
        },
        // Unique identifier for rows, can be used for unique row selection
        getRowId: (row) => row.id, // [!code highlight]
      });

      return (
        // ... render table
      );
    }
    ```
  </Step>

  <Step>
    Pass the table instance to the `DataTable`, and `DataTableToolbar` components:

    ```tsx
    import { DataTable } from "@/components/data-table/data-table";
    import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
    import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";

    function DataTableDemo() {
      return (
        <DataTable table={table}>
          <DataTableToolbar table={table}>
            <DataTableSortMenu table={table} />
          </DataTableToolbar>
        </DataTable>
      );
    }
    ```
  </Step>

  <Step>
    For advanced filtering, use the `DataTableAdvancedToolbar` component:

    ```tsx
    import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
    import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu";
    import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";

    function DataTableDemo() {
      return (
        <DataTable table={table}>
          <DataTableAdvancedToolbar table={table}>
            <DataTableFilterMenu table={table} />
            <DataTableSortMenu table={table} />
          </DataTableAdvancedToolbar>
        </DataTable>
      );
    }
    ```
  </Step>

  <Step>
    Alternatively, swap out `DataTableFilterMenu` with `DataTableCommandFilterMenu` for a command palette-style interface:

    ```tsx
    import { DataTableAdvancedToolbar } from "@/components/data-table/data-table-advanced-toolbar";
    import { DataTableFilterMenu } from "@/components/data-table/data-table-filter-menu"; // [!code --]
    import { DataTableCommandFilterMenu } from "@/components/data-table/data-table-command-filter-menu"; // [!code ++]
    import { DataTableSortMenu } from "@/components/data-table/data-table-sort-menu";

    function DataTableDemo() {
      return (
        <DataTable table={table}>
          <DataTableAdvancedToolbar table={table}>
            {/* [!code --] */}
            <DataTableFilterMenu table={table} />
            {/* [!code ++] */}
            <DataTableCommandFilterMenu table={table} />
            <DataTableSortMenu table={table} />
          </DataTableAdvancedToolbar>
        </DataTable>
      );
    }
    ```
  </Step>

  <Step>
    Render an action bar on row selection:

    ```tsx
    import { ActionBar } from "@/components/ui/action-bar";

    function TableActionBar({ table }: { table: Table<Data> }) {
      const rows = table.getFilteredSelectedRowModel().rows;

      const onOpenChange = React.useCallback((open: boolean) => {
        if (!open) {
          table.toggleAllRowsSelected(false);
        }
      },
      [table],
    );
      
      return (
        <ActionBar open={rows.length > 0} onOpenChange={onOpenChange}>
          {/* Add your custom actions here */}
        </ActionBar>
      );
    }

    function DataTableDemo() {
      return (
        <DataTable 
          table={table}
          actionBar={<TableActionBar table={table} />}
        >
          <DataTableToolbar table={table} />
        </DataTable>
      );
    }
    ```
  </Step>
</Steps>

## Row Selection [#row-selection]

Use `getDataTableSelectColumn` to add a checkbox column for selecting rows:

```tsx
import { getDataTableSelectColumn } from "@/components/data-table/data-table-select-column";

const columns = React.useMemo<ColumnDef<DataTableFeatures, Project>[]>(
  () => [
    getDataTableSelectColumn(),
    // ...other columns
  ],
  [],
);
```

Cells are memoized and only re-render when the state they subscribe to changes. If you render your own selection-dependent cell, read the selection inside `Subscribe` instead of calling `row.getIsSelected()` directly:

```tsx
import { Subscribe } from "@tanstack/react-table";

cell: ({ row }) => (
  <Subscribe
    source={row.table.atoms.rowSelection}
    selector={(selection) => selection[row.id] === true}
  >
    {(isSelected) => (
      <Checkbox
        checked={isSelected}
        onCheckedChange={(value) => row.toggleSelected(!!value)}
      />
    )}
  </Subscribe>
),
```

## Row Actions [#row-actions]

Use `getDataTableActionsColumn` to add a menu of actions to each row:

```tsx
import { getDataTableActionsColumn } from "@/components/data-table/data-table-actions-column";
import { DropdownMenuItem } from "@/components/ui/dropdown-menu";

const columns = React.useMemo<ColumnDef<DataTableFeatures, Project>[]>(
  () => [
    // ...other columns
    getDataTableActionsColumn({
      actions: ({ row }) => (
        <DropdownMenuItem onClick={() => onRowDelete(row.original)}>
          Delete
        </DropdownMenuItem>
      ),
    }),
  ],
  [onRowDelete],
);
```

Pin it to the end with `initialState.columnPinning.end`, like `{ start: ["select"], end: ["actions"] }`.

## Client and Server Mode [#client-and-server-mode]

`useDataTable` runs in one of two modes. Both keep pagination, sorting, and filters in the URL.

<PropsTable
  variant="title"
  data="[
  {
    title: &#x22;server&#x22;,
    description: &#x22;Default. Pass the current page of `data` and the total `pageCount` (required). Read the URL state on the server and query your database.&#x22;,
  },
  {
    title: &#x22;client&#x22;,
    description: &#x22;Pass all rows as `data` and omit `pageCount`. The hook sorts, filters, and paginates them in the browser and derives the page count.&#x22;,
  },
]"
/>

`pageCount` is required in server mode and not allowed in client mode. TypeScript reports an error if you pass it in client mode or leave it out in server mode.

### Client Mode [#client-mode]

Use client mode when the full dataset fits in the browser:

```tsx
const { table } = useDataTable({
  mode: "client",
  data,
  columns,
  getRowId: (row) => row.id,
});
```

### Server Mode [#server-mode]

Use server mode for large datasets. Describe the filterable and sortable columns once, and share that config between the server and the column definitions.

<Steps>
  <Step>
    Define the column configs and search params:

    ```ts title="lib/validations.ts"
    import { createSearchParamsCache } from "nuqs/server";

    import type { DataTableColumnConfig } from "@/lib/data-table-types";
    import { getDataTableSearchParams } from "@/lib/data-table-parsers";

    export const tasksColumnConfigs = {
      // Sortable, not filterable
      code: { isSortable: false },
      title: { variant: "text" },
      status: { variant: "multiSelect" },
      estimatedHours: { variant: "range" },
      createdAt: { variant: "dateRange" },
    } as const satisfies Record<string, DataTableColumnConfig>;

    export const searchParamsCache = createSearchParamsCache(
      getDataTableSearchParams({
        columnConfigs: tasksColumnConfigs,
        defaultSorting: [{ id: "createdAt", desc: true }],
      }),
    );
    ```
  </Step>

  <Step>
    Parse the search params on the server and turn them into a query:

    ```tsx title="app/page.tsx"
    import { getDataTableQuery } from "@/lib/data-table-parsers";

    export default async function Page(props: {
      searchParams: Promise<Record<string, string | string[] | undefined>>;
    }) {
      const search = searchParamsCache.parse(await props.searchParams);
      // { page, perPage, sorting, filters, joinOperator }
      const query = getDataTableQuery(search, tasksColumnConfigs);
      const { data, pageCount } = await getTasks(query);

      return <TasksTable data={data} pageCount={pageCount} />;
    }
    ```

    Type the query function's input with `DataTableColumnConfigsQuery<typeof tasksColumnConfigs>`. Each filter has an `id`, `variant`, `operator`, and `value` to map onto your database query.
  </Step>

  <Step>
    Spread `getColumnOptions` into each column so filtering and sorting match the config:

    ```tsx
    import { getColumnOptions } from "@/lib/data-table-parsers";

    {
      id: "title",
      accessorKey: "title",
      meta: { label: "Title", variant: "text" },
      ...getColumnOptions(tasksColumnConfigs.title), // [!code highlight]
    }
    ```
  </Step>

  <Step>
    Pass the server data and `pageCount` to `useDataTable`. Pass `startTransition` from `React.useTransition()` to show loading states while the server re-renders:

    ```tsx
    const [isPending, startTransition] = React.useTransition();

    const { table } = useDataTable({
      data,
      columns,
      pageCount,
      startTransition,
    });
    ```
  </Step>
</Steps>

### URL Format [#url-format]

Each filterable column has its own search param, keyed by column id. The value is the operator followed by the filter value. When a filter uses the column's default operator, the operator is left out.

```txt
?title=report                     # text, default operator (contains)
?title=eq.Weekly%20report         # text, "is"
?status=todo,done                 # multi-select, default operator (has any of)
?estimatedHours=2,8               # range, default operator (between)
?estimatedHours=gt.4              # range, "is greater than"
?createdAt=is.empty               # no value
?sort=createdAt.desc,title.asc
?joinOperator=or
```

## API Reference [#api-reference]

### Column Definitions [#column-definitions]

The column definitions are used to define the columns of the data table.

```tsx
const columns = React.useMemo<ColumnDef<Project>[]>(() => [
  {
    // Required: Unique identifier for the column
    id: "title", // [!code highlight]
    // Required: Key to access the data, `accessorFn` can also be used
    accessorKey: "title", // [!code highlight]
    // Optional: Custom header component
    header: ({ column }) => (
      <DataTableColumnHeader column={column} label="Title" />
    ),
    // Optional: Custom cell component
    cell: ({ row }) => <div>{row.getValue("title")}</div>,
    // Optional: Meta options for filtering, sorting, and view options
    meta: {
      label: "Title",
      placeholder: "Search titles...",
      variant: "text",
      icon: Text,
    },
    // By default, the column will not be filtered. Set to `true` to enable filtering.
    enableColumnFilter: true, // [!code highlight]
  },
  {
    id: "status",
    // Access nested data using `accessorFn`
    accessorFn: (row) => row.lineItem.status,
    header: "Status",
    meta: {
      label: "Status",
      variant: "select",
      options: [
        { label: "Active", value: "active" },
        { label: "Inactive", value: "inactive" },
      ],
    },
    enableColumnFilter: true,
  },
], []);
```

#### Properties [#properties]

Core configuration options for defining columns.

<PropsTable
  data="[
  {
    title: &#x22;id&#x22;,
    description: &#x22;Required: Unique identifier for the column&#x22;,
  },
  {
    title: &#x22;accessorKey&#x22;,
    description: &#x22;Required: Key to access the data from the row&#x22;,
  },
  {
    title: &#x22;accessorFn&#x22;,
    description: &#x22;Optional: Custom accessor function to access data&#x22;,
  },
  {
    title: &#x22;header&#x22;,
    description: &#x22;Optional: Custom header component with column props&#x22;,
  },
  {
    title: &#x22;cell&#x22;,
    description: &#x22;Optional: Custom cell component with row props&#x22;,
  },
  {
    title: &#x22;meta&#x22;,
    description: &#x22;Optional: Meta options for accessing column metadata&#x22;,
  },
  {
    title: &#x22;enableColumnFilter&#x22;,
    description: &#x22;By default, the column will not be filtered. Set to `true` to enable filtering&#x22;,
  },
  {
    title: &#x22;enableSorting&#x22;,
    description: &#x22;Enable sorting for this column&#x22;,
  },
  {
    title: &#x22;enableHiding&#x22;,
    description: &#x22;Enable column visibility toggle&#x22;,
  },
]"
/>

#### Column Meta [#column-meta]

Column meta options for filtering, sorting, and view options.

<PropsTable
  data="[
  {
    title: &#x22;label&#x22;,
    description: &#x22;The display name for the column&#x22;,
  },
  {
    title: &#x22;placeholder&#x22;,
    description: &#x22;The placeholder text for filter inputs&#x22;,
  },
  {
    title: &#x22;variant&#x22;,
    description: &#x22;The type of filter to use (`text`, `number`, `select`, etc.)&#x22;,
  },
  {
    title: &#x22;options&#x22;,
    description: &#x22;For select/multi-select filters, an array of options with `label`, `value`, and optional `count` and `icon`&#x22;,
  },
  {
    title: &#x22;range&#x22;,
    description: &#x22;For range filters, a tuple of `[min, max]` values&#x22;,
  },
  {
    title: &#x22;unit&#x22;,
    description: &#x22;For numeric filters, the unit to display (e.g., 'hr', '$')&#x22;,
  },
  {
    title: &#x22;icon&#x22;,
    description: &#x22;The react component to use as an icon for the column&#x22;,
  },
]"
/>

#### Filter Variants [#filter-variants]

Available filter variants for [column meta](#column-meta).

<PropsTable
  variant="title"
  data="[
  {
    title: &#x22;text&#x22;,
    description: &#x22;Text search with contains, equals, etc.&#x22;,
  },
  {
    title: &#x22;number&#x22;,
    description: &#x22;Numeric filters with equals, greater than, less than, etc.&#x22;,
  },
  {
    title: &#x22;range&#x22;,
    description: &#x22;Range filters with minimum and maximum values&#x22;,
  },
  {
    title: &#x22;date&#x22;,
    description: &#x22;Date filters with equals, before, after, etc.&#x22;,
  },
  {
    title: &#x22;dateRange&#x22;,
    description: &#x22;Date range filters with start and end dates&#x22;,
  },
  {
    title: &#x22;boolean&#x22;,
    description: &#x22;Boolean filters with true/false values&#x22;,
  },
  {
    title: &#x22;select&#x22;,
    description: &#x22;Single-select filters with predefined options&#x22;,
  },
  {
    title: &#x22;multiSelect&#x22;,
    description: &#x22;Multi-select filters with predefined options&#x22;,
  },
]"
/>

Reference the [TanStack Table Column Definitions Guide](https://tanstack.com/table/latest/docs/guide/column-defs#column-definitions-guide) for detailed column definition guide.

### useDataTable [#usedatatable]

A hook for initializing the data table with state management.

<AutoTypeTable path="./types/radix/data-table.ts" name="UseDataTableProps" />

### DataTable [#datatable]

The main data table component.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableProps" />

### getDataTableActionsColumn [#getdatatableactionscolumn]

A utility function that returns an actions column with a dropdown menu for each row.

<AutoTypeTable path="./types/radix/data-table.ts" name="GetDataTableActionsColumnProps" />

### DataTableColumnHeader [#datatablecolumnheader]

Custom header component for columns with sorting.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableColumnHeaderProps" />

### DataTableToolbar [#datatabletoolbar]

Standard toolbar with filtering and view options.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableToolbarProps" />

### DataTableAdvancedToolbar [#datatableadvancedtoolbar]

Advanced toolbar with more comprehensive filtering capabilities.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableAdvancedToolbarProps" />

### DataTableViewOptions [#datatableviewoptions]

Controls column visibility and display preferences in the data table.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableViewOptionsProps" />

### DataTableSortMenu [#datatablesortmenu]

List of applied sorting with ability to add, remove, and modify sorting.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableSortMenuProps" />

### DataTableFilterMenu [#datatablefiltermenu]

List of applied filters with ability to add, remove, and modify filters.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableFilterMenuProps" />

### DataTableCommandFilterMenu [#datatablecommandfiltermenu]

Command palette-style filter menu with ability to add, remove, and modify filters.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTableCommandFilterMenuProps" />

### DataTablePagination [#datatablepagination]

Pagination controls for the data table.

<AutoTypeTable path="./types/radix/data-table.ts" name="DataTablePaginationProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Ctrl + Shift + F&#x22;, &#x22;Cmd + Shift + F&#x22;],
    description: &#x22;Toggles the filter menu.&#x22;,
  },
  {
    keys: [&#x22;Ctrl + Shift + S&#x22;, &#x22;Cmd + Shift + S&#x22;],
    description: &#x22;Toggles the sort menu.&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;, &#x22;Delete&#x22;],
    description: &#x22;Removes the focused filter/sort item. Removes the last applied filter/sort when menu trigger is focused.&#x22;,
  },
]"
/>

## Features [#features]

* **Advanced Filtering** - Multiple filter types (text, number, date, select, multi-select) with customizable operators
* **URL State Management** - Sync table state with URL search params using [nuqs](https://nuqs.47ng.com)
* **Sorting** - Multi-column sorting with persistent state
* **Pagination** - Server-side or client-side pagination with customizable page sizes
* **Column Visibility** - Toggle column visibility with view options menu
* **Row Selection** - Single or multi-row selection with action bar
* **Column Pinning** - Pin columns to left or right for better UX
* **Keyboard Navigation** - Full keyboard support with shortcuts for filter and sort menus
* **Responsive** - Mobile-first design with overflow handling
* **Customizable** - Flexible API for custom filters, columns, and actions

## Credits [#credits]

* [shadcn/ui](https://github.com/shadcn-ui/ui/tree/main/apps/www/app/\(app\)/examples/tasks) - For the initial implementation of the data table.


# Editable
URL: /docs/components/radix/editable



<ComponentTabs name="editable-demo" className="items-start justify-start [&>div]:pt-20" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/editable
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="editable" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Editable,
  EditableLabel,
  EditableArea,
  EditablePreview,
  EditableInput,
  EditableTrigger,
  EditableToolbar,
  EditableSubmit,
  EditableCancel,
} from "@/components/ui/editable";

return (
  <Editable>
    <EditableLabel />
    <EditableArea>
      <EditablePreview />
      <EditableInput />
      <EditableTrigger />
    </EditableArea>
    <EditableTrigger />
    <EditableToolbar>
      <EditableSubmit />
      <EditableCancel />
    </EditableToolbar>
  </Editable>
)
```

## Examples [#examples]

### With Double Click [#with-double-click]

Trigger edit mode with double click instead of single click.

<ComponentTabs name="editable-double-click-demo" className="items-start justify-start [&>div]:pt-20" />

### With Autosize [#with-autosize]

Input that automatically resizes based on content.

<ComponentTabs name="editable-autosize-demo" className="items-start justify-start [&>div]:pt-20" />

### Todo List [#todo-list]

<ComponentTabs name="editable-todo-list-demo" />

### With Form [#with-form]

Control the editable component in a form.

<ComponentTabs name="editable-form-demo" className="items-start justify-start [&>div]:pt-20" />

## API Reference [#api-reference]

### Editable [#editable]

The main container component for editable functionality.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableProps" />

### EditableLabel [#editablelabel]

The label component for the editable field.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableLabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the editable field is invalid&#x22;,
  },
  {
    title: &#x22;[data-required]&#x22;,
    value: &#x22;Present when the editable field is required&#x22;,
  },
]"
/>

### EditableArea [#editablearea]

Container for the preview and input components.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableAreaProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-editing]&#x22;,
    value: &#x22;Present when the field is in edit mode&#x22;,
  },
]"
/>

### EditablePreview [#editablepreview]

The preview component that displays the current value.

<AutoTypeTable path="./types/radix/editable.ts" name="EditablePreviewProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-empty]&#x22;,
    value: &#x22;Present when the field has no value&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the field is read-only&#x22;,
  },
]"
/>

### EditableInput [#editableinput]

The input component for editing the value.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableInputProps" />

### EditableTrigger [#editabletrigger]

Button to trigger edit mode.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the editable field is disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the field is read-only&#x22;,
  },
]"
/>

### EditableToolbar [#editabletoolbar]

Container for action buttons.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableToolbarProps" />

### EditableSubmit [#editablesubmit]

Button to submit changes.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableSubmitProps" />

### EditableCancel [#editablecancel]

Button to cancel changes.

<AutoTypeTable path="./types/radix/editable.ts" name="EditableCancelProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Submits the current value when in edit mode.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Cancels editing and reverts to the previous value.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
]"
/>


# Faceted
URL: /docs/components/radix/faceted



<ComponentTabs name="faceted-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/faceted
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install cmdk radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add cmdk radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add cmdk radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add cmdk radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Install the command and popover components from shadcn/ui.
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npx shadcn@latest add command popover
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm dlx shadcn@latest add command popover
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn dlx shadcn@latest add command popover
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun x shadcn@latest add command popover
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="faceted" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  Faceted,
  FacetedClear,
  FacetedContent,
  FacetedEmpty,
  FacetedGroup,
  FacetedInput,
  FacetedItem,
  FacetedItemIndicator,
  FacetedList,
  FacetedLoading,
  FacetedTrigger,
  FacetedValue,
} from "@/components/ui/faceted";

return (
  <Faceted>
    <FacetedTrigger>
      <FacetedValue />
    </FacetedTrigger>
    <FacetedContent>
      <FacetedInput />
      <FacetedList>
        <FacetedLoading />
        <FacetedEmpty />
        <FacetedGroup>
          <FacetedItem>
            <FacetedItemIndicator />
          </FacetedItem>
        </FacetedGroup>
        <FacetedClear />
      </FacetedList>
    </FacetedContent>
  </Faceted>
)
```

## Examples [#examples]

### Multiple [#multiple]

Set `multiple` to select more than one value. `FacetedItemIndicator` can show a count until the item is selected, and `FacetedClear` appears once something is selected.

<ComponentTabs name="faceted-multiple-demo" />

### Groups [#groups]

Split items into groups with headings, and separate them with `FacetedSeparator`.

<ComponentTabs name="faceted-groups-demo" />

### Async [#async]

Search on the server by setting `shouldFilter={false}` on `FacetedContent` and controlling the search with `value` and `onValueChange` on `FacetedInput`. Show `FacetedLoading` while a request is pending. Keep the selected options in `items` so their badges stay labeled when they aren't in the current results.

<ComponentTabs name="faceted-async-demo" />

### Controlled [#controlled]

Control the selection with `value` and `onValueChange`.

<ComponentTabs name="faceted-controlled-demo" />

## API Reference [#api-reference]

### Faceted [#faceted]

The root component. It holds the selection and the popover's open state.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedProps" />

### FacetedTrigger [#facetedtrigger]

The button that opens the popover. Use `asChild` to render your own button.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedTriggerProps" />

### FacetedValue [#facetedvalue]

Shows the current selection inside the trigger, as badges or a placeholder. Labels come from the `items` passed to `Faceted`.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedValueProps" />

### FacetedBadgeList [#facetedbadgelist]

The container for the selection badges.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedBadgeListProps" />

### FacetedBadge [#facetedbadge]

A badge for one selected option.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedBadgeProps" />

### FacetedContent [#facetedcontent]

The popover content. It wraps its children in a command menu.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedContentProps" />

### FacetedInput [#facetedinput]

The search input that filters the items. Set `variant="line"` for a plain row with a divider below it.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedInputProps" />

### FacetedList [#facetedlist]

The scrollable list of groups and items.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedListProps" />

### FacetedEmpty [#facetedempty]

Shown when no items match the search.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedEmptyProps" />

### FacetedLoading [#facetedloading]

Shown while results are loading, such as during a server search.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedLoadingProps" />

### FacetedGroup [#facetedgroup]

A group of items with an optional heading.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedGroupProps" />

### FacetedItem [#faceteditem]

A selectable option.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-checked]&#x22;,
    value: &#x22;Present when the item is selected.&#x22;,
  },
  {
    title: &#x22;[data-selected]&#x22;,
    value: &#x22;Present when the item is highlighted.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
]"
/>

### FacetedItemIndicator [#faceteditemindicator]

The check shown on selected items. Its children, such as a count, show while the item isn't selected.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedItemIndicatorProps" />

### FacetedClear [#facetedclear]

An item that clears the selection, in its own group below a separator. It only renders when something is selected.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedClearProps" />

### FacetedSeparator [#facetedseparator]

A line between groups.

<AutoTypeTable path="./types/radix/faceted.ts" name="FacetedSeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;When focus is on the trigger, opens the popover.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves the highlight to the next or previous item.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;, &#x22;End&#x22;],
    description: &#x22;Moves the highlight to the first or last item.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Selects or deselects the highlighted item.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the popover and returns focus to the trigger.&#x22;,
  },
]"
/>


# File Upload
URL: /docs/components/radix/file-upload



<ComponentTabs name="file-upload-demo" align="start" className="p-8" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/file-upload
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hook into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="file-upload" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  FileUpload,
  FileUploadDropzone,
  FileUploadTrigger,
  FileUploadList,
  FileUploadItem,
  FileUploadItemPreview,
  FileUploadItemMetadata,
  FileUploadItemProgress,
  FileUploadItemDelete,
  FileUploadClear,
} from "@/components/ui/file-upload";

return (
  <FileUpload>
    <FileUploadDropzone />
    <FileUploadTrigger />
    <FileUploadList>
      <FileUploadItem>
        <FileUploadItemPreview />
        <FileUploadItemMetadata />
        <FileUploadItemProgress />
        <FileUploadItemDelete />
      </FileUploadItem>
    </FileUploadList>
    <FileUploadClear />
  </FileUpload>
)
```

## Examples [#examples]

### With Validation [#with-validation]

Validate files with the `onFileValidate` prop on the `Root` component based on type, size, and custom rules. This will override the default file rejection message.

<ComponentTabs name="file-upload-validation-demo" align="start" className="p-8" />

### Direct Upload [#direct-upload]

Upload files directly with the `onUpload` prop on the `Root` component.

<ComponentTabs name="file-upload-direct-upload-demo" align="start" className="p-8" />

### Circular Progress [#circular-progress]

Render a circular progress indicator instead of a linear one by enabling the `circular` prop on the `ItemProgress` component.

<ComponentTabs name="file-upload-circular-progress-demo" align="start" />

### Fill Progress [#fill-progress]

Render a fill progress indicator instead of a linear one by enabling the `fill` prop on the `ItemProgress` component.

<ComponentTabs name="file-upload-fill-progress-demo" align="start" />

### With uploadthing [#with-uploadthing]

Integrate with [uploadthing](https://uploadthing.com) for secure, type-safe file uploads with real-time progress tracking.

<ComponentTabs name="file-upload-uploadthing-demo" align="start" className="p-8" />

### With Chat Input [#with-chat-input]

Integrate into a chat input for uploading files. For demo the `Dropzone` is absolutely positioned to cover the entire viewport.

<ComponentTabs name="file-upload-chat-input-demo" align="start" />

### With Form [#with-form]

Use the `value` and `onValueChange` props to handle file uploads with validation and submission.

<ComponentTabs name="file-upload-form-demo" align="start" className="p-8" />

## API Reference [#api-reference]

### FileUpload [#fileupload]

The main container component for the file upload functionality.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadProps" />

### FileUploadDropzone [#fileuploaddropzone]

A container for drag and drop functionality.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadDropzoneProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the dropzone is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when files are being dragged over the dropzone.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when there was an error with the files being uploaded.&#x22;,
  },
]"
/>

### FileUploadTrigger [#fileuploadtrigger]

A button that opens the file selection dialog.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the trigger is disabled.&#x22;,
  }
]"
/>

### FileUploadList [#fileuploadlist]

A container for displaying uploaded files.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
]"
/>

### FileUploadItem [#fileuploaditem]

Individual file item component.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadItemProps" />

### FileUploadItemPreview [#fileuploaditempreview]

Displays a preview of the file, showing an image for image files or an appropriate icon for other file types.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadItemPreviewProps" />

### FileUploadItemMetadata [#fileuploaditemmetadata]

Displays file information such as name, size, and error messages.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadItemMetadataProps" />

### FileUploadItemProgress [#fileuploaditemprogress]

Shows the upload progress for a file.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadItemProgressProps" />

### FileUploadItemDelete [#fileuploaditemdelete]

A button to remove a file from the list.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadItemDeleteProps" />

### FileUploadClear [#fileuploadclear]

A button to clear all files from the list.

<AutoTypeTable path="./types/radix/file-upload.ts" name="FileUploadClearProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the clear button is disabled.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;When focus is on the dropzone or trigger, opens the file selection dialog.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus between the dropzone, trigger, and file delete buttons.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;When the dropzone is focused, moves focus away from the dropzone.&#x22;,
  },
]"
/>

## Credits [#credits]

* [Building a Hold to Delete Component](https://emilkowal.ski/ui/building-a-hold-to-delete-component) - For the fill progress indicator.


# FPS
URL: /docs/components/radix/fps



<ComponentTabs name="fps-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/fps
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="fps" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Examples [#examples]

### Positioning Strategy [#positioning-strategy]

Control whether the FPS counter uses `fixed` or `absolute` positioning.

<ComponentTabs name="fps-strategy-demo" />

### Custom Position [#custom-position]

Choose from four corner positions for the FPS counter.

```tsx
import { Fps } from "@/components/fps"

export default function App() {
  return (
    <div>
      <Fps position="bottom-left" />
      {/* Your app content */}
    </div>
  )
}
```

### Custom Thresholds [#custom-thresholds]

Configure warning and error thresholds for color-coded performance indicators.

```tsx
import { Fps } from "@/components/fps"

export default function App() {
  return (
    <div>
      <Fps 
        warningThreshold={45}
        errorThreshold={30}
      />
      {/* Your app content */}
    </div>
  )
}
```

### Conditional Rendering [#conditional-rendering]

Enable the FPS counter only in development environments.

```tsx
import { Fps } from "@/components/fps"

export default function App() {
  const isDevelopment = process.env.NODE_ENV === "development"
  
  return (
    <div>
      <Fps enabled={isDevelopment} />
      {/* Your app content */}
    </div>
  )
}
```

## API Reference [#api-reference]

### Fps [#fps]

A component that displays a real-time FPS counter overlay.

<AutoTypeTable path="./types/radix/fps.ts" name="FpsProps" />

## Features [#features]

* **Real-time monitoring**: Uses `requestAnimationFrame` for accurate FPS measurement
* **Color-coded display**: Automatically changes color based on performance thresholds
  * Green: Good performance (above warning threshold)
  * Yellow: Warning (below warning threshold)
  * Red: Poor performance (below error threshold)
* **Flexible positioning**: Choose between `fixed` and `absolute` positioning strategies
* **Customizable position**: Choose from four corner positions
* **Configurable update interval**: Control how often the FPS value updates
* **Performance optimized**: Minimal overhead with efficient frame counting

## Positioning Strategies [#positioning-strategies]

### Fixed Positioning [#fixed-positioning]

When using `strategy="fixed"`, the FPS counter is positioned relative to the viewport and rendered via a portal into the document body. This is useful when you want the counter to remain visible while scrolling.

```tsx
<Fps strategy="fixed" position="top-right" />
```

### Absolute Positioning [#absolute-positioning]

When using `strategy="absolute"`, the FPS counter is rendered directly in place (without a portal) and positioned relative to its nearest positioned ancestor. This is useful when you want the counter to be contained within a specific element with a `relative` wrapper.

```tsx
<div className="relative">
  <Fps strategy="absolute" position="bottom-left" />
</div>
```

**Note:** Unlike `fixed` positioning, `absolute` positioning does not use a portal, so the component will respect relative positioning contexts and be contained within its parent element.

## Performance Considerations [#performance-considerations]

The FPS counter uses `requestAnimationFrame` to measure frame rate, which has minimal performance impact. The component:

* Only updates the display at the specified interval (default: 500ms)
* Uses refs to avoid unnecessary re-renders
* Automatically cleans up animation frames on unmount

For production builds, consider disabling the FPS counter:

```tsx
<Fps enabled={process.env.NODE_ENV === "development"} />
```


# Gauge
URL: /docs/components/radix/gauge



<ComponentTabs name="gauge-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/gauge
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="gauge" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import {
  Gauge,
  GaugeIndicator,
  GaugeTrack,
  GaugeRange,
  GaugeValueText,
  GaugeLabel,
} from "@/components/ui/gauge";

return (
  <Gauge>
    <GaugeIndicator>
      <GaugeTrack />
      <GaugeRange />
    </GaugeIndicator>
    <GaugeValueText />
    <GaugeLabel>Label</GaugeLabel>
  </Gauge>
)
```

Or use the `Combined` component to get all the parts in one.

```tsx
import { GaugeCombined } from "@/components/ui/gauge";

<GaugeCombined label="Performance" />
```

## Examples [#examples]

### Sizes [#sizes]

Different gauge sizes to fit various UI contexts.

<ComponentTabs name="gauge-sizes-demo" />

### Colors [#colors]

Different color themes for various use cases like system monitoring, health indicators, and status displays.

<ComponentTabs name="gauge-colors-demo" />

### Variants [#variants]

Different arc configurations including semi-circle, three-quarter circle, and full circle gauges.

<ComponentTabs name="gauge-variants-demo" />

## Value Text Formatting [#value-text-formatting]

By default, the gauge displays the percentage value (0–100) based on `value`, `min`, and `max`. You can customize the format using the `getValueText` prop:

### Show Percentage [#show-percentage]

```tsx
<Gauge 
  value={85}
  getValueText={(value, min, max) => {
    const percentage = ((value - min) / (max - min)) * 100;
    return `${Math.round(percentage)}%`;
  }}
>
  {/* ... */}
</Gauge>
```

### Show Fraction [#show-fraction]

```tsx
<Gauge 
  value={75}
  max={100}
  getValueText={(value, min, max) => `${value}/${max}`}
>
  {/* ... */}
</Gauge>
```

### Custom Text [#custom-text]

```tsx
<Gauge 
  value={75}
  getValueText={(value) => `${value} points`}
>
  {/* ... */}
</Gauge>
```

## Theming [#theming]

The gauge component uses CSS `currentColor` for stroke colors, making it easy to theme using Tailwind's text utilities:

### Track Theming [#track-theming]

```tsx
<GaugeTrack className="text-blue-200 dark:text-blue-900" />
```

### Range Theming [#range-theming]

```tsx
<GaugeRange className="text-blue-500" />
```

### Value Text Theming [#value-text-theming]

```tsx
<GaugeValueText className="text-blue-700 dark:text-blue-300" />
```

### Label Theming [#label-theming]

```tsx
<GaugeLabel className="text-blue-600" />
```

## API Reference [#api-reference]

### Gauge [#gauge]

The main container component for the gauge.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current gauge value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized gauge value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### GaugeIndicator [#gaugeindicator]

The SVG container that holds the gauge arc paths.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current gauge value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-percentage]&#x22;,
    value: &#x22;The normalized gauge value as a decimal between 0 and 1 (only present when not indeterminate).&#x22;,
  },
]"
/>

### GaugeTrack [#gaugetrack]

The background arc that represents the full range of possible values.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeTrackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### GaugeRange [#gaugerange]

The portion of the arc that represents the current gauge value with smooth animations.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeRangeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The current gauge value (only present when not indeterminate).&#x22;,
  },
  {
    title: &#x22;[data-max]&#x22;,
    value: &#x22;The maximum gauge value.&#x22;,
  },
  {
    title: &#x22;[data-min]&#x22;,
    value: &#x22;The minimum gauge value.&#x22;,
  },
]"
/>

### GaugeValueText [#gaugevaluetext]

The text element that displays the current gauge value or custom content. Automatically centers within the arc's visual bounds.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeValueTextProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### GaugeLabel [#gaugelabel]

An optional label element that displays below the gauge.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeLabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;indeterminate&#x22;, &#x22;loading&#x22;, &#x22;complete&#x22;],
  },
]"
/>

### GaugeCombined [#gaugecombined]

The combined component that includes all the parts.

<AutoTypeTable path="./types/radix/gauge.ts" name="GaugeProps" />

## Accessibility [#accessibility]

### Screen Reader Support [#screen-reader-support]

* Uses the `meter` role for proper screen reader identification
* Provides `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext` attributes
* Supports `aria-labelledby` when a label prop is provided
* Supports indeterminate state by omitting `aria-valuenow` when value is null

## Notes [#notes]

* The component automatically handles indeterminate states when `value` is `null` or `undefined`
* Gauge values are automatically clamped to the valid range between `min` and `max`
* Invalid `max` or `value` props will log console errors and use fallback values
* Supports full circles (360°) by automatically splitting into two semi-circles for proper SVG rendering
* Value text automatically centers within the arc's visual bounds for both full and partial circles
* The gauge range uses `stroke-dashoffset` animations for smooth, performant filling effects
* All stroke colors use `currentColor` by default, making them responsive to text color changes
* Default angles are 0° (start) to 360° (end) for a full circle gauge


# Kanban
URL: /docs/components/radix/kanban



<ComponentTabs name="kanban-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/kanban
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="kanban" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnHandle,
  KanbanItem,
  KanbanItemHandle,
  KanbanOverlay,
} from "@/components/ui/kanban";

return (
  <Kanban>
    <KanbanBoard>
      <KanbanColumn>
        <KanbanColumnHandle />
        <KanbanItem>
          <KanbanItemHandle />
        </KanbanItem>
      </KanbanColumn>
    </KanbanBoard>
    <KanbanOverlay />
  </Kanban>
)
```

## Usage [#usage]

### With Primitive Values [#with-primitive-values]

When using primitive arrays (strings, numbers), the `getItemValue` prop is optional. The component will automatically use the items themselves as unique identifiers.

```tsx
const [columns, setColumns] = React.useState({
  todo: ["Task 1", "Task 2"],
  done: ["Task 3"],
});

<Kanban.Kanban value={columns} onValueChange={setColumns}>
  <Kanban.Board>
    {Object.entries(columns).map(([columnId, items]) => (
      <Kanban.Column key={columnId} value={columnId}>
        {items.map((item) => (
          <Kanban.Item key={item} value={item}>
            {item}
          </Kanban.Item>
        ))}
      </Kanban.Column>
    ))}
  </Kanban.Board>
</Kanban.Kanban>
```

### With Object Arrays [#with-object-arrays]

When using object arrays, the `getItemValue` prop is required to extract unique identifiers from each item.

```tsx
const [columns, setColumns] = React.useState({
  todo: [
    { id: 1, title: "Task 1" },
    { id: 2, title: "Task 2" },
  ],
  done: [
    { id: 3, title: "Task 3" },
  ],
});

<Kanban.Kanban
  value={columns}
  onValueChange={setColumns}
  getItemValue={(item) => item.id}
>
  <Kanban.Board>
    {Object.entries(columns).map(([columnId, items]) => (
      <Kanban.Column key={columnId} value={columnId}>
        {items.map((item) => (
          <Kanban.Item key={item.id} value={item.id}>
            {item.title}
          </Kanban.Item>
        ))}
      </Kanban.Column>
    ))}
  </Kanban.Board>
</Kanban.Kanban>
```

## Examples [#examples]

### With Dynamic Overlay [#with-dynamic-overlay]

Display a dynamic overlay when an item or column is being dragged.

<ComponentTabs name="kanban-dynamic-overlay-demo" />

## API Reference [#api-reference]

### Kanban [#kanban]

The main container component for kanban board functionality.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanProps" />

### KanbanBoard [#kanbanboard]

Container for kanban columns.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanBoardProps" />

### Column [#column]

Individual kanban column component.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanColumnProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the column is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the column is being dragged.&#x22;,
  },
]"
/>

### ColumnHandle [#columnhandle]

A button component that acts as a drag handle for kanban columns.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanColumnHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the column is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the parent column is being dragged.&#x22;,
  }
]"
/>

### KanbanItem [#kanbanitem]

Individual kanban item component.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the item is being dragged.&#x22;,
  },
]"
/>

### KanbanItemHandle [#kanbanitemhandle]

A button component that acts as a drag handle for kanban items.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanItemHandleProps" />

<DataAttributesTable
  data="[ 
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the parent item is being dragged.&#x22;,
  }
]"
/>

### Overlay [#overlay]

The overlay component that appears when an item or column is being dragged.

<AutoTypeTable path="./types/radix/kanban.ts" name="KanbanOverlayProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Picks up the kanban item or column for reordering when released, and drops it in its new position when pressed again.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves the kanban item up in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves the kanban item down in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves the kanban item left in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves the kanban item right in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;Esc&#x22;],
    description: &#x22;Cancels the drag operation and returns the item or column to its original position.&#x22;,
  },
]"
/>


# Kbd
URL: /docs/components/radix/kbd



<Callout type="warn">
  **Deprecated.** Kbd was removed from Dice UI in October 2025. shadcn/ui ships a [Kbd](https://ui.shadcn.com/docs/components/radix/kbd) component, so use that instead:

  <CodeBlockTabs defaultValue="npm" groupId="package-manager">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npx shadcn@latest add kbd
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm dlx shadcn@latest add kbd
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn dlx shadcn@latest add kbd
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun x shadcn@latest add kbd
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</Callout>

## Migrating [#migrating]

`@diceui/kbd` no longer installs. Replace it with shadcn/ui's `Kbd` and `KbdGroup`:

| Dice UI                            | shadcn/ui                                  |
| ---------------------------------- | ------------------------------------------ |
| `Kbd.Root` / `KbdRoot`             | `KbdGroup`                                 |
| `Kbd.Key` / `KbdKey`               | `Kbd`                                      |
| `Kbd.Separator` / `KbdSeparator`   | Text between keys, such as `+`, or nothing |
| `title` on `Kbd.Key`               | Wrap the key in `<abbr title="…">`         |
| `variant` and `size` on `Kbd.Root` | `className`                                |

```tsx
import * as Kbd from "@/components/ui/kbd"; // [!code --]
import { Kbd, KbdGroup } from "@/components/ui/kbd"; // [!code ++]

// Before
<Kbd.Root>
  <Kbd.Key>⌘</Kbd.Key>
  <Kbd.Separator />
  <Kbd.Key>K</Kbd.Key>
</Kbd.Root>

// After
<KbdGroup>
  <Kbd>
    <abbr title="Command">⌘</abbr>
  </Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

`Kbd.Key` added a `title` for common symbols such as ⌘, ⇧ and ⌥ automatically. shadcn/ui's `Kbd` doesn't, so add an `<abbr title>` where a symbol needs a description.


# Key Value
URL: /docs/components/radix/key-value



<ComponentTabs name="key-value-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/key-value
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="key-value" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  KeyValue,
  KeyValueList,
  KeyValueItem,
  KeyValueKeyInput,
  KeyValueValueInput,
  KeyValueRemove,
  KeyValueError,
  KeyValueAdd,
} from "@/components/ui/key-value";

return (
  <KeyValue>
    <KeyValueList>
      <KeyValueItem>
        <KeyValueKeyInput />
        <KeyValueValueInput />
        <KeyValueRemove />
        <KeyValueError field="key" />
        <KeyValueError field="value" />
      </KeyValueItem>
    </KeyValueList>
    <KeyValueAdd />
  </KeyValue>
)
```

## Examples [#examples]

### With Paste Support [#with-paste-support]

Paste multiple key-value pairs at once. Supports formats like `KEY=VALUE`, `KEY: VALUE`, and tab-separated values.

<ComponentTabs name="key-value-paste-demo" />

### With Validation [#with-validation]

Add validation rules for keys and values with error messages.

<ComponentTabs name="key-value-validation-demo" />

### With Form [#with-form]

Integrate with React Hook Form for form validation.

<ComponentTabs name="key-value-form-demo" />

## API Reference [#api-reference]

### KeyValue [#keyvalue]

The main container component that manages the key-value items state.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when any item has validation errors&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when read-only&#x22;,
  },
]"
/>

### KeyValueList [#keyvaluelist]

Container for rendering the list of key-value items.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: &#x22;vertical | horizontal&#x22;,
  },
]"
/>

### KeyValueItem [#keyvalueitem]

Individual key-value pair item container.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when item is highlighted/focused&#x22;,
  },
]"
/>

### KeyInput [#keyinput]

Input field for the key part of the item.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueKeyInputProps" />

### ValueInput [#valueinput]

Input field for the value part of the item.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueValueInputProps" />

### KeyValueRemove [#keyvalueremove]

Button to remove a key-value item.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueRemoveProps" />

### KeyValueAdd [#keyvalueadd]

Button to add a new key-value item.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueAddProps" />

### KeyValueError [#keyvalueerror]

Error message display for validation errors.

<AutoTypeTable path="types/radix/key-value.ts" name="KeyValueErrorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Navigate between key inputs, value inputs, and buttons.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Submit the current input value.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Cancel the current input.&#x22;,
  },
  {
    keys: [&#x22;Ctrl&#x22;, &#x22;V&#x22;],
    description: &#x22;Paste multiple key-value pairs (supports multiple formats).&#x22;,
  },
]"
/>

## Features [#features]

* **Dynamic Items**: Add and remove key-value pairs dynamically
* **Paste Support**: Paste multiple items at once in various formats (`KEY=VALUE`, `KEY: VALUE`, tab-separated)
* **Validation**: Built-in validation for keys and values with custom validators
* **Duplicate Detection**: Optional prevention of duplicate keys
* **Item Limits**: Set minimum and maximum item counts
* **Form Integration**: Works seamlessly with React Hook Form
* **Controlled/Uncontrolled**: Supports both controlled and uncontrolled patterns
* **Accessibility**: Full keyboard navigation and screen reader support
* **Customizable**: Fully customizable styling and behavior

## Paste Formats [#paste-formats]

The component supports pasting multiple key-value pairs in the following formats:

```
KEY=VALUE
DATABASE_URL=postgresql://localhost:5432
API_KEY=sk-1234567890

KEY: VALUE
DATABASE_URL: postgresql://localhost:5432
API_KEY: sk-1234567890

KEY	VALUE (tab-separated)
DATABASE_URL	postgresql://localhost:5432
API_KEY	sk-1234567890
```

When pasting multiple lines, the component will automatically parse and create separate items for each line.


# Listbox
URL: /docs/components/radix/listbox



<ComponentTabs name="listbox-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/listbox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/listbox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/listbox
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/listbox
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/listbox
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/listbox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/listbox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/listbox
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/listbox
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="listbox" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ListboxRoot,
  ListboxGroup,
  ListboxGroupLabel,
  ListboxItem,
  ListboxItemIndicator,
} from "@diceui/listbox"

return (
  <ListboxRoot>
    <ListboxGroup>
      <ListboxGroupLabel/>
      <ListboxItem >
        <ListboxItemIndicator />
      </ListboxItem>
    </ListboxGroup>
  </ListboxRoot>
)
```

## Examples [#examples]

### Horizontal Orientation [#horizontal-orientation]

Set `orientation="horizontal"` to create a horizontally navigable list.

<ComponentTabs name="listbox-horizontal-demo" />

### Grid Layout [#grid-layout]

For grid layouts, use `orientation="mixed"` to enable navigation in both directions.
Use CSS Grid to arrange the items in a grid structure. In grid layouts,
arrow keys will navigate accordingly:

* Up/Down: Navigates within a column
* Left/Right: Navigates within a row

<ComponentTabs name="listbox-grid-demo" />

### Grouped Items [#grouped-items]

Group items together to create a list of related options.

<ComponentTabs name="listbox-group-demo" />

## API Reference [#api-reference]

### Listbox [#listbox]

The root component for creating listboxes.

<AutoTypeTable path="./types/radix/listbox.ts" name="RootProps" />

### ListboxGroup [#listboxgroup]

A group of items inside the selectable list.

<AutoTypeTable path="./types/radix/listbox.ts" name="GroupProps" />

### ListboxGroupLabel [#listboxgrouplabel]

A label for the group of items.

<AutoTypeTable path="./types/radix/listbox.ts" name="GroupLabelProps" />

### ListboxItem [#listboxitem]

An item inside the selectable list.

<AutoTypeTable path="./types/radix/listbox.ts" name="ItemProps" />

### ListboxItemIndicator [#listboxitemindicator]

A visual indicator that shows when the item is selected.

<AutoTypeTable path="./types/radix/listbox.ts" name="ItemIndicatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Focuses the last active item in the list.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to previous focusable item in the list.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves highlighting to previous item in vertical lists.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves highlighting to next item in vertical lists.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves highlighting to previous item in horizontal lists.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves highlighting to next item in horizontal lists.&#x22;,
  },
]"
/>


# Marquee
URL: /docs/components/radix/marquee



<ComponentTabs name="marquee-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/marquee
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/marquee
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/marquee
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/marquee
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="marquee" />

      <Step>
        Add the following CSS animations to your 

        `globals.css`

         file:
      </Step>

      ```css
      :root {
        --animate-marquee-left: marquee-left var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-right: marquee-right var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-left-rtl: marquee-left-rtl var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-right-rtl: marquee-right-rtl var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-up: marquee-up var(--marquee-duration) linear var(--marquee-loop-count);
        --animate-marquee-down: marquee-down var(--marquee-duration) linear var(--marquee-loop-count);

      @keyframes marquee-left {
        0% {
          transform: translateX(0%);
        }
        100% {
          transform: translateX(calc(-100% - var(--marquee-gap)));
        }
      }

      @keyframes marquee-right {
        0% {
          transform: translateX(calc(-100% - var(--marquee-gap)));
        }
        100% {
          transform: translateX(0%);
        }
      }

      @keyframes marquee-up {
        0% {
          transform: translateY(0%);
        }
        100% {
          transform: translateY(calc(-100% - var(--marquee-gap)));
        }
      }

      @keyframes marquee-down {
        0% {
          transform: translateY(calc(-100% - var(--marquee-gap)));
        }
        100% {
          transform: translateY(0%);
        }
      }

      @keyframes marquee-left-rtl {
        0% {
          transform: translateX(0%);
        }
        100% {
          transform: translateX(calc(100% + var(--marquee-gap)));
        }
      }

      @keyframes marquee-right-rtl {
        0% {
          transform: translateX(calc(100% + var(--marquee-gap)));
        }
        100% {
          transform: translateX(0%);
        }
      }
      }
      ```
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts and compose them together.

```tsx
import * as Marquee from "@/components/ui/marquee"

return (
  <Marquee.Root>
    <Marquee.Content>
      <Marquee.Item />
    </Marquee.Content>
    <Marquee.Edge side="left" />
    <Marquee.Edge side="right" />
  </Marquee.Root>
)
```

## Examples [#examples]

### Logo Showcase [#logo-showcase]

Use the marquee to showcase logos or brands in a continuous scroll.

<ComponentTabs name="marquee-logo-demo" />

### Vertical Layout [#vertical-layout]

Use `side` to control the direction of the marquee.

<ComponentTabs name="marquee-vertical-demo" />

### With RTL [#with-rtl]

The marquee component automatically adapts to RTL (right-to-left) layouts.

<ComponentTabs name="marquee-rtl-demo" />

## API Reference [#api-reference]

### Marquee [#marquee]

The main marquee component that creates continuous scrolling animations.

<AutoTypeTable path="./types/radix/marquee.ts" name="MarqueeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--marquee-duration&#x22;,
    description: &#x22;The duration of the marquee animation in seconds. Calculated based on content size and speed.&#x22;,
    defaultValue: &#x22;Calculated dynamically (e.g., 20s)&#x22;,
  },
  {
    title: &#x22;--marquee-gap&#x22;,
    description: &#x22;The gap between marquee items and repetitions.&#x22;,
    defaultValue: &#x22;1rem&#x22;,
  },
  {
    title: &#x22;--marquee-delay&#x22;,
    description: &#x22;The delay before the marquee animation starts in seconds.&#x22;,
    defaultValue: &#x22;0s&#x22;,
  },
  {
    title: &#x22;--marquee-loop-count&#x22;,
    description: &#x22;The number of times the animation should repeat. Can be a number or 'infinite'.&#x22;,
    defaultValue: &#x22;infinite&#x22;,
  },
]"
/>

### MarqueeContent [#marqueecontent]

Contains the scrolling content and handles repetition for seamless animation.

<AutoTypeTable path="./types/radix/marquee.ts" name="MarqueeContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### MarqueeItem [#marqueeitem]

Individual items within the marquee content.

<AutoTypeTable path="./types/radix/marquee.ts" name="MarqueeItemProps" />

### MarqueeEdge [#marqueeedge]

Edge overlay components for smooth gradient transitions.

<AutoTypeTable path="./types/radix/marquee.ts" name="MarqueeEdgeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-size]&#x22;,
    value: [&#x22;default&#x22;, &#x22;sm&#x22;, &#x22;lg&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Pauses or resumes the marquee animation when pauseOnKeyboard is enabled.&#x22;,
  },
]"
/>

## Features [#features]

* **RTL Support**: Automatically adapts to RTL (right-to-left) layouts
* **Screen Reader Support**: Content remains accessible to assistive technologies
* **Reduced Motion**: Respects user's `prefers-reduced-motion` setting
* **Pause Controls**:
  * **Hover**: Can be configured to pause animation when hovered
  * **Keyboard**: Press Space key to pause/resume (when `pauseOnKeyboard` is enabled)
* **Focus Management**: Proper focus indicators and keyboard navigation when `pauseOnKeyboard` is enabled


# Mask Input
URL: /docs/components/radix/mask-input



<ComponentTabs name="mask-input-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/mask-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="mask-input" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import and use the component directly.

```tsx
import { MaskInput } from "@/components/ui/mask-input";

<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
  maskPlaceholder="(___) ___-____"
  onValueChange={(masked, unmasked) => {
    console.log('Masked:', masked);     // "(555) 123-4567"
    console.log('Unmasked:', unmasked); // "5551234567"
  }}
/>
```

## Features [#features]

* **Smart cursor positioning** - Cursor stays in the correct position during typing and pasting
* **Paste support** - Intelligently handles pasted content with proper formatting
* **Built-in patterns** - Common formats like phone, SSN, date, credit card, etc.
* **Custom patterns** - Create your own mask patterns with validation
* **Optional mask placeholders** - Control when mask format hints are shown with `maskPlaceholder`
* **TypeScript support** - Full type safety with IntelliSense
* **Accessibility** - ARIA attributes and keyboard navigation
* **Form integration** - Works seamlessly with form libraries
* **Composition support** - Use `asChild` prop to render as a different component using Radix Slot

## Examples [#examples]

### With custom patterns [#with-custom-patterns]

Create custom mask patterns for specific formatting needs.

<ComponentTabs name="mask-input-custom-pattern-demo" />

### With validation modes [#with-validation-modes]

Control when validation occurs with different validation modes, similar to react-hook-form.

<ComponentTabs name="mask-input-validation-modes-demo" />

### Card information [#card-information]

Card information with credit card number, expiry date, and CVC fields.

<ComponentTabs name="mask-input-card-information-demo" />

### With form [#with-form]

Integrate masked inputs with form validation using react-hook-form.

<ComponentTabs name="mask-input-form-demo" />

## Built-in Mask Patterns [#built-in-mask-patterns]

The component includes several predefined mask patterns:

| Pattern            | Format                | Example             | Description                                 |
| ------------------ | --------------------- | ------------------- | ------------------------------------------- |
| `phone`            | `(###) ###-####`      | (555) 123-4567      | US phone number                             |
| `ssn`              | `###-##-####`         | 123-45-6789         | Social Security Number                      |
| `date`             | `##/##/####`          | 12/25/2023          | Date (MM/DD/YYYY)                           |
| `time`             | `##:##`               | 14:30               | Time (HH:MM)                                |
| `creditCard`       | `#### #### #### ####` | 1234 5678 9012 3456 | Credit card number                          |
| `creditCardExpiry` | `##/##`               | 12/25               | Credit card expiry date (MM/YY)             |
| `zipCode`          | `#####`               | 12345               | US ZIP code                                 |
| `zipCodeExtended`  | `#####-####`          | 12345-6789          | US ZIP+4 code                               |
| `currency`         | Dynamic               | \$1,234.56          | Currency formatting using Intl.NumberFormat |
| `percentage`       | `##.##%`              | 12.34%              | Percentage with decimals                    |
| `licensePlate`     | `###-###`             | ABC-123             | License plate format                        |
| `ipv4`             | `###.###.###.###`     | 192.168.1.1         | IPv4 address                                |
| `macAddress`       | `##:##:##:##:##:##`   | 00:1B:44:11:3A:B7   | MAC address                                 |
| `isbn`             | `###-#-###-#####-#`   | 978-0-123-45678-9   | ISBN-13 book identifier                     |
| `ein`              | `##-#######`          | 12-3456789          | Employer Identification Number              |

## Custom Mask Patterns [#custom-mask-patterns]

Create custom patterns using the `MaskPattern` interface:

```tsx
const customPattern: MaskPattern = {
  pattern: "###-###-####",
  transform: (value, opts) => value.replace(/[^A-Z0-9]/gi, "").toUpperCase(),
  validate: (value, opts) => value.length === 10,
};

<MaskInput 
  mask={customPattern} 
  placeholder="Enter license plate"
  maskPlaceholder="ABC-1234"
/>
```

## Currency Formatting [#currency-formatting]

The currency mask uses the `Intl.NumberFormat` API for localization and currency formatting.

```tsx
// Default USD formatting
<MaskInput mask="currency" />

// Euro formatting with German locale
<MaskInput 
  mask="currency" 
  currency="EUR" 
  locale="de-DE" 
/>

// Japanese Yen formatting
<MaskInput 
  mask="currency" 
  currency="JPY" 
  locale="ja-JP" 
/>

// British Pound formatting
<MaskInput 
  mask="currency" 
  currency="GBP" 
  locale="en-GB" 
/>
```

## Mask Placeholders [#mask-placeholders]

Use the `maskPlaceholder` prop to control when mask format hints are shown. The mask placeholder only appears when the input is focused and the prop is provided.

```tsx
// Shows mask placeholder when focused
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
  maskPlaceholder="(___) ___-____"
/>

// No mask placeholder - just regular placeholder behavior
<MaskInput 
  mask="phone" 
  placeholder="Enter phone number"
/>
```

## API Reference [#api-reference]

### MaskInput [#maskinput]

The main masked input component that handles formatting and user input.

<AutoTypeTable path="./types/radix/mask-input.ts" name="MaskInputProps" />

### MaskPattern [#maskpattern]

Interface for creating custom mask patterns.

<AutoTypeTable path="./types/radix/mask-input.ts" name="MaskPattern" />

### MaskPatternKey [#maskpatternkey]

Predefined mask pattern keys for common input formats.

| Pattern            | Description                                 |
| ------------------ | ------------------------------------------- |
| `phone`            | US phone number                             |
| `ssn`              | Social Security Number                      |
| `date`             | Date (MM/DD/YYYY)                           |
| `time`             | Time (HH:MM)                                |
| `creditCard`       | Credit card number                          |
| `creditCardExpiry` | Credit card expiry date (MM/YY)             |
| `zipCode`          | US ZIP code                                 |
| `zipCodeExtended`  | US ZIP+4 code                               |
| `currency`         | Currency formatting using Intl.NumberFormat |
| `percentage`       | Percentage with decimals                    |
| `licensePlate`     | License plate format                        |
| `ipv4`             | IPv4 address                                |
| `macAddress`       | MAC address                                 |
| `isbn`             | ISBN-13 book identifier                     |
| `ein`              | Employer Identification Number              |

### TransformOptions [#transformoptions]

Options passed to the transform function for advanced formatting.

<AutoTypeTable path="./types/radix/mask-input.ts" name="TransformOptions" />

### ValidateOptions [#validateoptions]

Options passed to the validate function for enhanced validation.

<AutoTypeTable path="./types/radix/mask-input.ts" name="ValidateOptions" />

## Data Attributes [#data-attributes]

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the input is disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the input has validation errors.&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the input is read-only.&#x22;,
  },
  {
    title: &#x22;[data-required]&#x22;,
    value: &#x22;Present when the input is required.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to or away from the input.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;Removes the previous character, intelligently handling mask characters.&#x22;,
  },
  {
    keys: [&#x22;Delete&#x22;],
    description: &#x22;Removes the next character.&#x22;,
  },
  {
    keys: [&#x22;Ctrl + V&#x22;, &#x22;Cmd + V&#x22;],
    description: &#x22;Pastes content with intelligent mask formatting.&#x22;,
  },
  {
    keys: [&#x22;Ctrl + A&#x22;, &#x22;Cmd + A&#x22;],
    description: &#x22;Selects all input content.&#x22;,
  },
]"
/>


# Masonry
URL: /docs/components/radix/masonry



<ComponentTabs name="masonry-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/masonry
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="masonry" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Masonry,
  MasonryItem,
} from "@/components/ui/masonry";

return (
  <Masonry>
    <MasonryItem />
  </Masonry>
)
```

## Examples [#examples]

### Linear Layout [#linear-layout]

Set `linear` to `true` to maintain item order from left to right.

<ComponentTabs name="masonry-linear-demo" />

### Server Side Rendering [#server-side-rendering]

Use `defaultWidth` and `defaultHeight`, and item `fallback` to render items on the server. This is useful for preventing layout shift and hydration errors.

<ComponentTabs name="masonry-ssr-demo" />

## API Reference [#api-reference]

### Masonry [#masonry]

The main container component for the masonry layout.

<AutoTypeTable path="./types/radix/masonry.ts" name="MasonryProps" />

### MasonryItem [#masonryitem]

Individual item component within the masonry layout.

<AutoTypeTable path="./types/radix/masonry.ts" name="MasonryItemProps" />


# Media Player
URL: /docs/components/radix/media-player



<ComponentTabs name="media-player-demo" />

## Installation [#installation]

> **Prerequisites:** Before installing the media player component, you'll need to update your existing shadcn/ui components to support portal containers.

<Steps>
  <Step>
    **DropdownMenu**

    ```diff
    function DropdownMenuContent({
      className,
    + container,
      sideOffset = 4,
      ...props
    -}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
    +}: React.ComponentProps<typeof DropdownMenuPrimitive.Content> & {
    +  container?: DropdownMenuPrimitive.DropdownMenuPortalProps["container"];
    +}) {
      return (
    -    <DropdownMenuPrimitive.Portal>
    +    <DropdownMenuPrimitive.Portal container={container}>
    ```
  </Step>

  <Step>
    **Tooltip**

    ```diff
    function TooltipContent({
      className,
      sideOffset = 0,
    + container,
      children,
      ...props
    -}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
    +}: React.ComponentProps<typeof TooltipPrimitive.Content> & {
    +  container?: TooltipPrimitive.TooltipPortalProps["container"];
    +}) {
      return (
    -    <TooltipPrimitive.Portal>
    +    <TooltipPrimitive.Portal container={container}>
    ```
  </Step>
</Steps>

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <Steps>
      <Step>
        After completing the prerequisite component updates, install the media player:

        <CodeBlockTabs defaultValue="npm" groupId="package-manager">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest add @diceui/media-player
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Step>
    </Steps>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        After completing the prerequisite component updates, install the required dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hook into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="media-player" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  MediaPlayer,
  MediaPlayerVideo,
  MediaPlayerAudio,
  MediaPlayerLoading,
  MediaPlayerError,
  MediaPlayerVolumeIndicator,
  MediaPlayerControls,
  MediaPlayerControlsOverlay,
  MediaPlayerPlay,
  MediaPlayerSeekBackward,
  MediaPlayerSeekForward,
  MediaPlayerVolume,
  MediaPlayerSeek,
  MediaPlayerTime,
  MediaPlayerPlaybackSpeed,
  MediaPlayerLoop,
  MediaPlayerCaptions,
  MediaPlayerFullscreen,
  MediaPlayerDownload,
  MediaPlayerSettings,
} from "@/components/ui/media-player";

return (
  <MediaPlayer>
    <MediaPlayerVideo>
      <source src="..." type="video/mp4" />
    </MediaPlayerVideo>
    <MediaPlayerLoading />
    <MediaPlayerError />
    <MediaPlayerVolumeIndicator />
    <MediaPlayerControls>
      <MediaPlayerControlsOverlay />
      <MediaPlayerPlay />
      <MediaPlayerSeekBackward />
      <MediaPlayerSeekForward />
      <MediaPlayerVolume />
      <MediaPlayerSeek />
      <MediaPlayerTime />
      <MediaPlayerPlaybackSpeed />
      <MediaPlayerLoop />
      <MediaPlayerCaptions />
      <MediaPlayer.PiP />
      <MediaPlayer.Fullscreen />
      <MediaPlayer.Download />
    </MediaPlayer.Controls>
  </MediaPlayer.Root>
)
```

## Examples [#examples]

### Audio Player [#audio-player]

Use the `Audio` component instead of `Video` for audio playback.

<ComponentTabs name="media-player-audio-demo" />

### With Settings Menu [#with-settings-menu]

Media player with a settings menu with playback speed, caption option, and resolution selector.

<ComponentTabs name="media-player-settings-demo" />

### HLS Playback [#hls-playback]

Media player with HLS (HTTP Live Streaming) support for adaptive bitrate streaming.

This example demonstrates using the [Mux Video React](https://github.com/muxinc/elements/tree/main/packages/mux-video-react) package as the video element to enable HLS playback.

<ComponentTabs name="media-player-hls-demo" />

### With Error Handling [#with-error-handling]

Media player with custom error handling and retry functionality.

<ComponentTabs name="media-player-error-demo" />

### With Playlist [#with-playlist]

A media player example that includes a playlist, similar to music streaming applications.

<ComponentTabs name="media-player-playlist-demo" />

## API Reference [#api-reference]

### MediaPlayer [#mediaplayer]

The main container component for the media player.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-controls-visible]&#x22;,
    value: &#x22;Present when the controls are visible.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the media player is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
]"
/>

### MediaPlayerVideo [#mediaplayervideo]

The video element, integrated with the player state.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerVideoProps" />

### MediaPlayerAudio [#mediaplayeraudio]

The audio element, integrated with the player state.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerAudioProps" />

### MediaPlayerControls [#mediaplayercontrols]

A container for the media player controls.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerControlsProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the controls are disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
  {
    title: &#x22;[data-visible]&#x22;,
    value: &#x22;Present when the controls are visible.&#x22;,
  },
]"
/>

### MediaPlayerControlsOverlay [#mediaplayercontrolsoverlay]

Displays as a subtle backdrop that improves readability for media controls.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerControlsOverlayProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
  {
    title: &#x22;[data-visible]&#x22;,
    value: &#x22;Present when the controls are visible.&#x22;,
  },
]"
/>

### MediaPlayerLoading [#mediaplayerloading]

A loading indicator that appears when media is loading, similar to YouTube/Netflix style.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerLoadingProps" />

### MediaPlayerError [#mediaplayererror]

An error component that displays when media playback encounters an error, with retry and reload options.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerErrorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;fullscreen&#x22;, &#x22;windowed&#x22;],
  },
]"
/>

### MediaPlayerVolumeIndicator [#mediaplayervolumeindicator]

A volume indicator that appears when the volume is changed with keyboard interactions.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerVolumeIndicatorProps" />

### MediaPlayerPlay [#mediaplayerplay]

A button to play or pause the media.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerPlayProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerSeekBackward [#mediaplayerseekbackward]

A button to seek backward in the media.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerSeekBackwardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

### MediaPlayerSeekForward [#mediaplayerseekforward]

A button to seek forward in the media.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerSeekForwardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

### MediaPlayerSeek [#mediaplayerseek]

A slider component to seek through the media playback.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerSeekProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the slider is disabled.&#x22;,
  },
  {
    title: &#x22;[data-hovering]&#x22;,
    value: &#x22;Present when the seek slider is being actively hovered.&#x22;,
  },
  {
    title: &#x22;[data-slider='']&#x22;,
    value: &#x22;Present on the seek slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-container']&#x22;,
    value: &#x22;The container for the seek slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek']&#x22;,
    value: &#x22;The root for the seek slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-buffered']&#x22;,
    value: &#x22;The buffered progress indicator within the track.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-hover-range']&#x22;,
    value: &#x22;The hover preview range indicator.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-chapter-separator']&#x22;,
    value: &#x22;Chapter separators displayed on the track.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-thumbnail']&#x22;,
    value: &#x22;The thumbnail preview container in the tooltip.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-chapter-title']&#x22;,
    value: &#x22;The chapter title in the tooltip.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-seek-time']&#x22;,
    value: &#x22;The time display in the tooltip.&#x22;,
  },
]"
/>

#### Styling [#styling]

```tsx
<MediaPlayer.Seek 
  className={
    cn(
      "**:data-[slot='media-player-seek-buffered']:bg-primary/60",
      "**:data-[slot='media-player-seek-hover-range']:bg-primary/70",
      "**:data-[slot='media-player-seek-chapter-separator']:w-1 **:data-[slot='media-player-seek-chapter-separator']:bg-muted",
      "**:data-[slot='media-player-seek-thumbnail']:border-2 **:data-[slot='media-player-seek-thumbnail']:border-ring"
    )
  }
/>
```

### MediaPlayerVolume [#mediaplayervolume]

A slider component to control the media volume.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerVolumeProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the volume control is disabled.&#x22;,
  },
  {
    title: &#x22;[data-slider='']&#x22;,
    value: &#x22;Present on the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-volume-container']&#x22;,
    value: &#x22;The container for the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-volume-trigger']&#x22;,
    value: &#x22;The trigger for the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-slot='media-player-volume']&#x22;,
    value: &#x22;The root for the volume slider.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerTime [#mediaplayertime]

Displays the current time, duration, or remaining time of the media.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerTimeProps" />

### MediaPlayerPlaybackSpeed [#mediaplayerplaybackspeed]

A select dropdown to control the media playback speed.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerPlaybackSpeedProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the select is disabled.&#x22;,
  },
]"
/>

### MediaPlayerLoop [#mediaplayerloop]

A button to toggle loop mode.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerLoopProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },   
]"
/>

### MediaPlayerFullscreen [#mediaplayerfullscreen]

A button to toggle fullscreen mode.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerFullscreenProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerPiP [#mediaplayerpip]

A button to toggle picture in picture mode (video only).

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerPiPProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerCaptions [#mediaplayercaptions]

A button to toggle captions or subtitles (video only).

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerCaptionsProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### MediaPlayerDownload [#mediaplayerdownload]

A button to download the media file.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerDownloadProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

### MediaPlayerSettings [#mediaplayersettings]

A dropdown menu with playback speed selector, caption selector, and resolution selector.

<AutoTypeTable path="./types/radix/media-player.ts" name="MediaPlayerSettingsProps" />

**Features:**

* Playback speed control with customizable speeds
* Video quality/resolution selection (when available)
* Captions/subtitles control
* Organized in a clean dropdown interface

```tsx
<MediaPlayer.Settings 
  speeds={[0.5, 0.75, 1, 1.25, 1.5, 2]}
/>
```

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the button is disabled.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;, &#x22;K&#x22;],
    description: &#x22;Toggles play/pause.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Seeks forward 5 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Seeks backward 5 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;J&#x22;],
    description: &#x22;Seeks backward 10 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;L&#x22;],
    description: &#x22;Seeks forward 10 seconds (video only).&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowRight&#x22;],
    description: &#x22;Seeks forward 5 seconds (audio only).&#x22;,
  },
  {
    keys: [&#x22;Shift + ArrowLeft&#x22;],
    description: &#x22;Seeks backward 5 seconds (audio only).&#x22;,
  },
  {
    keys: [&#x22;0&#x22;, &#x22;1&#x22;, &#x22;2&#x22;, &#x22;3&#x22;, &#x22;4&#x22;, &#x22;5&#x22;, &#x22;6&#x22;, &#x22;7&#x22;, &#x22;8&#x22;, &#x22;9&#x22;],
    description: &#x22;Seeks to 0%-90% of duration.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Seeks to beginning.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Seeks to end.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Increases volume (video only).&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Decreases volume (video only).&#x22;,
  },
  {
    keys: [&#x22;M&#x22;],
    description: &#x22;Toggles mute.&#x22;,
  },
  {
    keys: [&#x22;R&#x22;],
    description: &#x22;Toggles repeat mode.&#x22;,
  },
  {
    keys: [&#x22;F&#x22;],
    description: &#x22;Toggles fullscreen.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Exits fullscreen when in fullscreen mode.&#x22;,
  },
  {
    keys: [&#x22;>&#x22;],
    description: &#x22;Increases playback speed.&#x22;,
  },
  {
    keys: [&#x22;<&#x22;],
    description: &#x22;Decreases playback speed.&#x22;,
  },
  {
    keys: [&#x22;C&#x22;],
    description: &#x22;Toggles captions (video only, if available).&#x22;,
  },
  {
    keys: [&#x22;P&#x22;],
    description: &#x22;Toggles Picture-in-Picture.&#x22;,
  },
  {
    keys: [&#x22;D&#x22;],
    description: &#x22;Downloads the media file (if download button is present).&#x22;,
  },
]"
/>

## Credits [#credits]

* [FASSounds](https://pixabay.com/users/fassounds-3433550/?utm_source=link-attribution\&utm_medium=referral\&utm_campaign=music\&utm_content=160166) - For the audio file used in basic examples.
* [Pika](https://pika.art) - For the video file used in basic examples.
* [Elephants Dream](https://orange.blender.org/) - Open movie by the Blender Foundation, used in settings demo under Creative Commons Attribution 2.5.
* [Mux](https://www.mux.com/) - For HLS video streaming and VTT files used in HLS and settings demos.
* [Media Chrome](https://www.media-chrome.org/) - For VTT chapter and caption files used in examples.
* [RandomMind](https://opengameart.org/users/randommind) - For "Medieval: Battle" track used in playlist demo, available under CC0 from OpenGameArt.org.
* [The Lemming Shepherds](https://www.dropbox.com/s/mvvwaw1msplnteq/City%20Lights%20-%20The%20Lemming%20Shepherds.mp3) - For "City Lights" track used in playlist demo.
* [Picsum](https://picsum.photos/) - For placeholder cover images used in playlist demo.


# Mention
URL: /docs/components/radix/mention



<ComponentTabs name="mention-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/mention
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/mention
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/mention
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/mention
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/mention
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/mention
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/mention
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/mention
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/mention
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="mention" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Mention,
  MentionLabel,
  MentionInput,
  MentionPortal,
  MentionContent,
  MentionItem,
} from "@diceui/mention";

return (
  <Mention>
    <MentionLabel />
    <MentionInput />
    <MentionPortal>
      <MentionContent>
        <MentionItem />
      </MentionContent>
    </MentionPortal>
  </Mention>
)
```

## Examples [#examples]

### Custom Trigger [#custom-trigger]

<ComponentTabs name="mention-custom-trigger-demo" />

### With Custom Filter [#with-custom-filter]

<ComponentTabs name="mention-custom-filter-demo" />

## API Reference [#api-reference]

### Mention [#mention]

The container for all mention parts. Mention tags can be styled using the `data-tag` attribute within the root.

<AutoTypeTable path="./types/radix/mention.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### MentionLabel [#mentionlabel]

An accessible label that describes the mention input. Associates with the input element for screen readers.

<AutoTypeTable path="./types/radix/mention.ts" name="LabelProps" />

### MentionInput [#mentioninput]

The text input field that users can type into to trigger mentions.

<AutoTypeTable path="./types/radix/mention.ts" name="InputProps" />

### MentionPortal [#mentionportal]

A portal for rendering the mention content outside of its DOM hierarchy.

<AutoTypeTable path="./types/radix/mention.ts" name="PortalProps" />

### MentionContent [#mentioncontent]

The popover container for mention items. Positions the mention popover relative to the cursor position.

<AutoTypeTable path="./types/radix/mention.ts" name="ContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--dice-transform-origin&#x22;,
    description: &#x22;Transform origin for cursor positioning.&#x22;,
  },
  {
    title: &#x22;--dice-available-width&#x22;,
    description: &#x22;Available width in the viewport for the popover element.&#x22;,
  },
  {
    title: &#x22;--dice-available-height&#x22;,
    description: &#x22;Available height in the viewport for the popover element.&#x22;,
  },
]"
/>

### MentionItem [#mentionitem]

An interactive option in the mention list.

<AutoTypeTable path="./types/radix/mention.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when the item is highlighted.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-value]&#x22;,
    value: &#x22;The value of the item.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When open, selects the highlighted mention option.&#x22;
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;When open, highlights the previous mention option.&#x22;
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;When open, highlights the next mention option.&#x22;
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;When open, highlights the first mention option.&#x22;
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;When open, highlights the last mention option.&#x22;
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the mention popover and returns focus to the input.&#x22;
  },
]"
/>


# Phone Input
URL: /docs/components/radix/phone-input



<ComponentTabs name="phone-input-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/phone-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-value-as-ref" />

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="phone-input" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  PhoneInput,
  PhoneInputCountrySelect,
  PhoneInputField,
} from "@/components/ui/phone-input";

return (
  <PhoneInput>
    <PhoneInputCountrySelect />
    <PhoneInputField />
  </PhoneInput>
)
```

## Examples [#examples]

### Custom Countries [#custom-countries]

Provide a custom list of countries to display in the dropdown.

<ComponentTabs name="phone-input-custom-countries-demo" />

### With Form [#with-form]

Use the phone input component in a form with validation.

<ComponentTabs name="phone-input-form-demo" />

## API Reference [#api-reference]

### PhoneInput [#phoneinput]

The root container component that acts as both the wrapper and input group. Handles layout, borders, and focus states.

<AutoTypeTable path="./types/radix/phone-input.ts" name="PhoneInputProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the phone input is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the phone input is invalid&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the phone input is read-only&#x22;,
  },
]"
/>

### PhoneInputCountrySelect [#phoneinputcountryselect]

The button component that triggers the country dropdown. Uses Popover and Command internally for the country list.

<AutoTypeTable path="./types/radix/phone-input.ts" name="PhoneInputCountrySelectProps" />

### PhoneInputField [#phoneinputfield]

The input field component for entering the phone number.

<AutoTypeTable path="./types/radix/phone-input.ts" name="PhoneInputFieldProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description:
      &#x22;Moves focus to the next focusable element (country select or phone input field).&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;, &#x22;Enter&#x22;],
    description: &#x22;Opens the country dropdown when focused on the country select button.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the country dropdown.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowDown&#x22;],
    description:
      &#x22;Navigate through country items when the dropdown is open.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;, &#x22;End&#x22;],
    description:
      &#x22;Jump to first or last country in the list.&#x22;,
  },
  {
    keys: [&#x22;Type to search&#x22;],
    description:
      &#x22;Filter countries by name, dial code, or country code as you type.&#x22;,
  },
]"
/>


# Presentation
URL: /docs/components/radix/presentation



<ComponentTabs name="presentation-demo" className="h-100 p-0" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/presentation
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/pptx
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/pptx
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/pptx
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/pptx
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hook into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-mobile" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="presentation" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

`@diceui/pptx` pulls in `@diceui/pptx-core` automatically. The thumbnail rail collapses below 768px behind a toggle, which is why this item also depends on `button` and `use-mobile`. The primitives themselves use a `render` prop (not `asChild`) even in a Radix project.

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Presentation,
  PresentationContent,
  PresentationError,
  PresentationLoading,
  PresentationSelection,
  PresentationSlide,
  PresentationThumbnailList,
  PresentationViewport,
} from "@/components/ui/presentation";

return (
  <Presentation>
    <PresentationThumbnailList />
    <PresentationContent>
      <PresentationLoading />
      <PresentationError />
      <PresentationViewport>
        <PresentationSlide>
          <PresentationSelection />
        </PresentationSlide>
      </PresentationViewport>
    </PresentationContent>
  </Presentation>
)
```

Pass a `File`, `Blob`, `ArrayBuffer`, or `Uint8Array` to `file` on `Presentation`. There is no toolbar in this item — toolbars are assembled around the primitives.

## Examples [#examples]

### Editing [#editing]

Load with `readOnly={false}` and place `PresentationSelection` inside `PresentationSlide` to move, resize, and edit text. Undo and redo shortcuts are opt-in via `undoRedoShortcuts`. Drag thumbnails to reorder slides.

This example also uses `PresentationZoomSelect`, a companion control built with `useZoom` and `select`. Install it with `@diceui/presentation-zoom-select`.

<ComponentTabs name="presentation-editing-demo" className="h-100 p-0" />

## API Reference [#api-reference]

### PresentationProvider [#presentationprovider]

Makes an existing store available to descendants without rendering any DOM. Use it when a toolbar has to sit outside `Presentation`, or when the store is created with `useCreatePresentationStore` before the tree mounts.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationProviderProps" />

### Presentation [#presentation]

The outermost component. Creates an internal store (or inherits one from `PresentationProvider`), loads the file, and provides context to all descendants.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationProps" />

### PresentationContent [#presentationcontent]

Layout wrapper for the viewport column next to the thumbnail rail.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationContentProps" />

### PresentationViewport [#presentationviewport]

Scrollable container that centers the slide and optionally auto-fits it to fill the available space. The styled wrapper defaults `autoFit` to `true` with 10px padding.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationViewportProps" />

### PresentationSlide [#presentationslide]

Renders the active slide as a scaled DOM tree. Mounts an empty wrapper immediately so sibling layout is stable. Children are placed in an overlay; put `PresentationSelection` here.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationSlideProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;idle&#x22;, &#x22;loading&#x22;, &#x22;ready&#x22;, &#x22;error&#x22;],
  },
]"
/>

### PresentationSelection [#presentationselection]

PowerPoint-style editing overlay. Enables drag-to-move, resize, inline text editing, multi-select, and keyboard shortcuts. Renders nothing unless the presentation was loaded with `readOnly={false}`.

Must be placed inside `PresentationSlide`.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationSelectionProps" />

<CSSVariablesTable
  data="[
  {
    title: &#x22;--presentation-selection&#x22;,
    description: &#x22;Accent color for the selection overlay, resize handles, and marquee.&#x22;,
    defaultValue: &#x22;var(--ring)&#x22;,
  },
]"
/>

### PresentationLoading [#presentationloading]

Renders its children only while the presentation is in the `"loading"` state.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationLoadingProps" />

### PresentationError [#presentationerror]

Renders its children only when the presentation fails to parse.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationErrorProps" />

### PresentationThumbnailList [#presentationthumbnaillist]

Scrollable list of slide thumbnails. Below 768px the rail collapses behind a toggle button and closes on outside pointerup or Escape.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationThumbnailListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-mobile]&#x22;,
    value: &#x22;Present when the viewport is below 768px.&#x22;,
  },
]"
/>

### PresentationThumbnailItem [#presentationthumbnailitem]

Clickable item for a single slide in a `PresentationThumbnailList`.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationThumbnailItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-active]&#x22;,
    value: &#x22;Present when this item's slide is the active slide.&#x22;,
  },
]"
/>

### PresentationThumbnailItemPreview [#presentationthumbnailitempreview]

Renders the slide miniature for the enclosing `PresentationThumbnailItem`. Previews are rendered lazily as they approach the viewport.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationThumbnailItemPreviewProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-pending]&#x22;,
    value: &#x22;Present while the miniature has not been rendered yet.&#x22;,
  },
]"
/>

### PresentationThumbnailItemNumber [#presentationthumbnailitemnumber]

Renders the 1-based slide number for the enclosing `PresentationThumbnailItem`.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationThumbnailItemNumberProps" />

### PresentationZoomSelect [#presentationzoomselect]

Companion select for Fit and explicit zoom levels. Must be used inside `PresentationProvider` or `Presentation`.

<AutoTypeTable path="./types/radix/presentation.ts" name="PresentationZoomSelectProps" />

### usePresentation [#usepresentation]

Subscribes to top-level presentation state: parse status, progress, and errors.

<AutoTypeTable path="./types/radix/presentation.ts" name="UsePresentationResult" />

### useSlide [#useslide]

Subscribes to slide navigation state and exposes navigation actions.

<AutoTypeTable path="./types/radix/presentation.ts" name="UseSlideResult" />

### useZoom [#usezoom]

Subscribes to zoom state. Setting an explicit level turns auto-fit off; `setAutoFit(true)` turns it back on.

<AutoTypeTable path="./types/radix/presentation.ts" name="UseZoomResult" />

### useHistory [#usehistory]

Undo, redo, and whether the deck has unsaved edits.

<AutoTypeTable path="./types/radix/presentation.ts" name="UseHistoryResult" />

Create a store with `useCreatePresentationStore` for programmatic `load`, `edit`, `save`, and `reset`. See the [store API](https://pptx.diceui.com/docs/store) for the full imperative surface.

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

#### Thumbnail list [#thumbnail-list]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowUp&#x22;, &#x22;ArrowDown&#x22;],
    description: &#x22;Moves focus and navigates to the previous or next slide.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves focus to the first slide.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves focus to the last slide.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the thumbnail rail on mobile.&#x22;,
  },
]"
/>

#### Selection overlay [#selection-overlay]

Available when the presentation is loaded with `readOnly={false}`.

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Arrow Keys&#x22;],
    description: &#x22;Nudges the selection by 1px. Hold Shift for 10px.&#x22;,
  },
  {
    keys: [&#x22;Delete&#x22;, &#x22;Backspace&#x22;],
    description: &#x22;Deletes the selected shapes.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Exits text editing, then deselects.&#x22;,
  },
  {
    keys: [&#x22;Ctrl/Cmd + A&#x22;],
    description: &#x22;Selects every shape on the slide.&#x22;,
  },
  {
    keys: [&#x22;Ctrl/Cmd + Z&#x22;],
    description: &#x22;Undo. Bound only when undoRedoShortcuts is true.&#x22;,
  },
  {
    keys: [&#x22;Ctrl/Cmd + Y&#x22;, &#x22;Ctrl/Cmd + Shift + Z&#x22;],
    description: &#x22;Redo. Bound only when undoRedoShortcuts is true.&#x22;,
  },
]"
/>


# QR Code
URL: /docs/components/radix/qr-code



<ComponentTabs name="qr-code-demo" className="items-center justify-center" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/qr-code
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui qrcode
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Install the type definitions:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @types/qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @types/qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @types/qrcode
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @types/qrcode
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hook into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="qr-code" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  QRCode,
  QRCodeCanvas,
  QRCodeSvg,
  QRCodeImage,
  QRCodeOverlay,
  QRCodeSkeleton,
  QRCodeDownload,
} from "@/components/ui/qr-code";

return (
  <QRCode>
    <QRCodeCanvas />
    <QRCodeSvg />
    <QRCodeImage />
    <QRCodeOverlay />
    <QRCodeSkeleton />
    <QRCodeDownload />
  </QRCode>
)
```

Swap `Canvas` with `Svg` or `Image` to render the qr code in svg and image formats respectively.

## Examples [#examples]

### Different Formats [#different-formats]

Render QR codes as Canvas, SVG, or Image elements.

<ComponentTabs name="qr-code-formats-demo" />

### Customization [#customization]

Customize colors, size, and error correction levels.

<ComponentTabs name="qr-code-customization-demo" />

### Overlay [#overlay]

Add logos, icons, or custom elements to the center of QR codes.

<ComponentTabs name="qr-code-overlay-demo" />

## API Reference [#api-reference]

### QRCode [#qrcode]

The main container component that provides context for QR code generation.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeProps" />

<CSSVariablesTable
  data="[
  {
    title: &#x22;--qr-code-size&#x22;,
    description: &#x22;The size of the QR code in pixels. Used to constrain child elements to the QR code dimensions.&#x22;,
    defaultValue: &#x22;Based on size prop (e.g., 200px)&#x22;,
  },
]"
/>

### Image [#image]

Renders the QR code as an HTML image element.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeImageProps" />

### Canvas [#canvas]

Renders the QR code using HTML5 Canvas.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeCanvasProps" />

### Svg [#svg]

Renders the QR code as an SVG element.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeSvgProps" />

### Overlay [#overlay-1]

Overlays content (like logos or icons) in the center of the QR code.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeOverlayProps" />

### Skeleton [#skeleton]

Displays a loading placeholder while the QR code is being generated. Automatically hides once the QR code is ready.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeSkeletonProps" />

### Download [#download]

A button component for downloading the QR code.

<AutoTypeTable path="./types/radix/qr-code.ts" name="QRCodeDownloadProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Activates the download button when focused.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Activates the download button when focused.&#x22;,
  },
]"
/>

## Error Correction Levels [#error-correction-levels]

QR codes support different error correction levels that determine how much of the code can be damaged while still being readable:

* **L (Low)**: \~7% of data can be restored
* **M (Medium)**: \~15% of data can be restored (default)
* **Q (Quartile)**: \~25% of data can be restored
* **H (High)**: \~30% of data can be restored

Higher error correction levels result in denser QR codes but provide better resilience to damage or distortion.

## Usage Notes [#usage-notes]

* The component uses dynamic imports to avoid SSR issues with the QR code library
* Canvas rendering provides the best performance for static QR codes
* SVG rendering is ideal for scalable, print-ready QR codes
* The download functionality works in all modern browsers
* QR codes are generated client-side for privacy and performance
* Child elements are automatically constrained by the `--qr-code-size` CSS variable to prevent layout issues
* When using the Overlay component, set `level="H"` (High error correction) to ensure the QR code remains scannable with up to 30% coverage


# Rating
URL: /docs/components/radix/rating



<ComponentTabs name="rating-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/rating
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/rating
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/rating
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/rating
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="rating" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import { Rating, RatingItem } from "@/components/ui/rating";

return (
  <Rating>
    <RatingItem />
  </Rating>
)
```

## Examples [#examples]

### Themes [#themes]

Customize the rating component with different colors and icons.

<ComponentTabs name="rating-themes-demo" />

### Controlled State [#controlled-state]

Control the rating value with state.

<ComponentTabs name="rating-controlled-demo" />

### With Form [#with-form]

Integrate the rating component with form validation.

<ComponentTabs name="rating-form-demo" />

## API Reference [#api-reference]

### Rating [#rating]

The main container component for the rating.

<AutoTypeTable path="./types/radix/rating.ts" name="RatingProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when readonly&#x22;,
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### RatingItem [#ratingitem]

Individual rating item (star) component.

<AutoTypeTable path="./types/radix/rating.ts" name="RatingItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when readonly&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;empty&#x22;, &#x22;partial&#x22;, &#x22;full&#x22;],
  },
  {
    title: &#x22;[data-hovered]&#x22;,
    value: &#x22;Present when hovered&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;ArrowLeft&#x22;, &#x22;ArrowRight&#x22;],
    description: &#x22;Navigate between rating items.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Move to the first rating item.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Move to the last rating item.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Activate the focused rating item (when activationMode is 'manual').&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Clear the rating (when clearable is true).&#x22;,
  },
]"
/>


# Relative Time Card
URL: /docs/components/radix/relative-time-card



<ComponentTabs name="relative-time-card-demo" className="h-[450px]" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/relative-time-card
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="relative-time-card" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Examples [#examples]

### With Multiple Timezones [#with-multiple-timezones]

<ComponentTabs name="relative-time-card-timezones-demo" />

### With Variants [#with-variants]

<ComponentTabs name="relative-time-card-variants-demo" />

## API Reference [#api-reference]

### RelativeTimeCard [#relativetimecard]

The main component that displays relative time with hover functionality.

<AutoTypeTable path="./types/radix/relative-time-card.ts" name="RelativeTimeCardProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    description: &#x22;The state of the hover card&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Opens/closes the relative time card.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Opens the relative time card if closed.&#x22;,
  },
]"
/>

## Credits [#credits]

* [John Phamous](https://x.com/JohnPhamous/status/1836091528911216803) - For the initial implementation.


# Responsive Dialog
URL: /docs/components/radix/responsive-dialog



<ComponentTabs name="responsive-dialog-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/responsive-dialog
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install vaul
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add vaul
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add vaul
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add vaul
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-value-as-ref" />

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-mobile" />

      <Step>
        Copy and paste the dialog and drawer components into your project.
      </Step>

      <ComponentSource name="dialog" />

      <ComponentSource name="drawer" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="responsive-dialog" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ResponsiveDialog,
  ResponsiveDialogContent,
  ResponsiveDialogDescription,
  ResponsiveDialogFooter,
  ResponsiveDialogHeader,
  ResponsiveDialogTitle,
  ResponsiveDialogTrigger,
} from "@/components/ui/responsive-dialog";

<ResponsiveDialog>
  <ResponsiveDialogTrigger />
  <ResponsiveDialogContent>
    <ResponsiveDialogHeader>
      <ResponsiveDialogTitle />
      <ResponsiveDialogDescription />
    </ResponsiveDialogHeader>
    <ResponsiveDialogFooter />
  </ResponsiveDialogContent>
</ResponsiveDialog>
```

## Examples [#examples]

### Confirmation Dialog [#confirmation-dialog]

Use the responsive dialog to confirm destructive actions like deleting items.

<ComponentTabs name="responsive-dialog-confirm-demo" />

### Variant Styling [#variant-styling]

Each component exposes a `data-variant` attribute that can be used to apply different styles based on whether the dialog or drawer is rendered.

```tsx
<ResponsiveDialogContent className="data-[variant=drawer]:pb-8 data-[variant=dialog]:max-w-md">
  {/* content */}
</ResponsiveDialogContent>

<ResponsiveDialogFooter className="data-[variant=drawer]:flex-col data-[variant=dialog]:flex-row">
  {/* buttons */}
</ResponsiveDialogFooter>
```

## API Reference [#api-reference]

### ResponsiveDialog [#responsivedialog]

The root component that manages the dialog/drawer state.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogProps" />

### ResponsiveDialogTrigger [#responsivedialogtrigger]

The button that opens the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogContent [#responsivedialogcontent]

The content container for the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogHeader [#responsivedialogheader]

The header section of the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogHeaderProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogFooter [#responsivedialogfooter]

The footer section of the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogFooterProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogTitle [#responsivedialogtitle]

The title of the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogTitleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogDescription [#responsivedialogdescription]

The description of the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogDescriptionProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogClose [#responsivedialogclose]

The close button for the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogCloseProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogOverlay [#responsivedialogoverlay]

The overlay behind the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogOverlayProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

### ResponsiveDialogPortal [#responsivedialogportal]

The portal container for the dialog/drawer.

<AutoTypeTable path="./types/radix/responsive-dialog.ts" name="ResponsiveDialogPortalProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;dialog&#x22;, &#x22;drawer&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

Adheres to the [Dialog WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Opens/closes the dialog when focus is on the trigger.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Opens/closes the dialog when focus is on the trigger.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the dialog/drawer and moves focus to the trigger.&#x22;,
  },
]"
/>


# Scroll Spy
URL: /docs/components/radix/scroll-spy



<ComponentTabs name="scroll-spy-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/scroll-spy
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="scroll-spy" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  ScrollSpy,
  ScrollSpyNav,
  ScrollSpyLink,
  ScrollSpyViewport,
  ScrollSpySection,
} from "@/components/ui/scroll-spy";

return (
  <ScrollSpy>
    <ScrollSpyNav>
      <ScrollSpyLink />
    </ScrollSpyNav>
    <ScrollSpyViewport>
      <ScrollSpySection />
    </ScrollSpyViewport>
  </ScrollSpy>
)
```

## Examples [#examples]

### Vertical Orientation [#vertical-orientation]

Set `orientation="vertical"` for content with vertical navigation.

<ComponentTabs name="scroll-spy-vertical-demo" />

### Controlled State [#controlled-state]

Use the `value` and `onValueChange` props to control the active section externally.

<ComponentTabs name="scroll-spy-controlled-demo" />

### Sticky Layout [#sticky-layout]

For full-page scroll behavior, you can use a sticky positioned navigation sidebar that stays fixed while the content scrolls. This works with the default window scroll (no `scrollContainer` prop needed).

```tsx
<ScrollSpy offset={100}>
  <ScrollSpyNav className="sticky top-20 h-fit">
    <ScrollSpyLink value="introduction">Introduction</ScrollSpyLink>
    <ScrollSpyLink value="getting-started">Getting Started</ScrollSpyLink>
    <ScrollSpyLink value="usage">Usage</ScrollSpyLink>
    <ScrollSpyLink value="api-reference">API Reference</ScrollSpyLink>
  </ScrollSpyNav>

  <ScrollSpyViewport>
    <ScrollSpySection value="introduction">
      <h2>Introduction</h2>
      <p>Your content here...</p>
    </ScrollSpySection>
    
    <ScrollSpySection value="getting-started">
      <h2>Getting Started</h2>
      <p>Your content here...</p>
    </ScrollSpySection>
    
    {/* More content sections */}
  </ScrollSpyViewport>
</ScrollSpy>
```

The key is to apply `sticky top-[offset]` to the `ScrollSpyNav` to keep the navigation visible as the page scrolls.

## API Reference [#api-reference]

### ScrollSpy [#scrollspy]

The root component that manages scroll tracking and contains all ScrollSpy parts.

<AutoTypeTable path="./types/radix/scroll-spy.ts" name="ScrollSpyProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### Nav [#nav]

The navigation container component.

<AutoTypeTable path="./types/radix/scroll-spy.ts" name="ScrollSpyNavProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### Link [#link]

Navigation link that scrolls to a section.

<AutoTypeTable path="./types/radix/scroll-spy.ts" name="ScrollSpyLinkProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
]"
/>

### Viewport [#viewport]

The viewport container component for sections.

<AutoTypeTable path="./types/radix/scroll-spy.ts" name="ScrollSpyViewportProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### Section [#section]

Content section that gets tracked by the scroll spy.

<AutoTypeTable path="./types/radix/scroll-spy.ts" name="ScrollSpySectionProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Shortcuts [#keyboard-shortcuts]

The ScrollSpy component follows standard link navigation patterns:

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Move focus between navigation items.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Activate the focused navigation item and scroll to the associated section.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Activate the focused navigation item and scroll to the associated section.&#x22;,
  },
]"
/>


# Scroller
URL: /docs/components/radix/scroller



<ComponentTabs name="scroller-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/scroller
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="scroller" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import { Scroller } from "@/components/ui/scroller"

<Scroller>
   {/* Scrollable content */}
</Scroller>
```

## Examples [#examples]

### Horizontal Scroll [#horizontal-scroll]

Set the `orientation` to `horizontal` to enable horizontal scrolling.

<ComponentTabs name="scroller-horizontal-demo" />

### Hidden Scrollbar [#hidden-scrollbar]

Set the `hideScrollbar` to `true` to hide the scrollbar while maintaining scroll functionality.

<ComponentTabs name="scroller-hidden-demo" />

### Navigation Buttons [#navigation-buttons]

Set the `withNavigation` to `true` to enable navigation buttons.

<ComponentTabs name="scroller-navigation-demo" />

## API Reference [#api-reference]

### Scroller [#scroller]

The main scrollable container component.

<AutoTypeTable path="./types/radix/scroller.ts" name="ScrollerProps" />


# Segmented Input
URL: /docs/components/radix/segmented-input



<ComponentTabs name="segmented-input-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/segmented-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="segmented-input" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import * as SegmentedInput from "@/components/ui/segmented-input";

return (
  <SegmentedInput.Root>
    <SegmentedInput.Item />
  </SegmentedInput.Root>
)
```

## Examples [#examples]

### Form Input [#form-input]

Use segmented inputs for structured form data like phone numbers or addresses.

<ComponentTabs name="segmented-input-form-demo" />

### RGB Color Input [#rgb-color-input]

Create color input controls using segmented inputs for RGB values.

<ComponentTabs name="segmented-input-rgb-demo" />

### Vertical Layout [#vertical-layout]

Display segmented inputs in a vertical orientation.

<ComponentTabs name="segmented-input-vertical-demo" />

## API Reference [#api-reference]

### SegmentedInput [#segmentedinput]

The main segmented input container.

<AutoTypeTable path="./types/radix/segmented-input.ts" name="SegmentedInputProps" />

### SegmentedInputItem [#segmentedinputitem]

Individual input items within the segmented input.

<AutoTypeTable path="./types/radix/segmented-input.ts" name="SegmentedInputItemProps" />

## Accessibility [#accessibility]

The SegmentedInput component follows standard web accessibility practices. Users navigate between inputs using Tab and Shift+Tab keys, which is the expected behavior for form controls.

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next input in the segment.&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous input in the segment.&#x22;,
  },
]"
/>


# Selection Toolbar
URL: /docs/components/radix/selection-toolbar



<ComponentTabs name="selection-toolbar-demo" align="start" className="p-8" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/selection-toolbar
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-value-as-ref" />

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="selection-toolbar" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  SelectionToolbar,
  SelectionToolbarItem,
  SelectionToolbarSeparator,
} from "@/components/ui/selection-toolbar";

return (
  <SelectionToolbar>
    <SelectionToolbarItem />
    <SelectionToolbarSeparator />
  </SelectionToolbar>
)
```

## Examples [#examples]

### Selection Info [#selection-info]

Track selection information with the `onSelectionChange` callback to display word count, character count, and other metrics.

<ComponentTabs name="selection-toolbar-info-demo" align="start" className="p-8" />

## API Reference [#api-reference]

### SelectionToolbar [#selectiontoolbar]

The root component that manages the toolbar's visibility and positioning.

<AutoTypeTable path="./types/radix/selection-toolbar.ts" name="SelectionToolbarProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--selection-toolbar-available-width&#x22;,
    description: &#x22;The available width in the viewport for the toolbar to fit within, accounting for collision boundaries.&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 1200px)&#x22;,
  },
  {
    title: &#x22;--selection-toolbar-available-height&#x22;,
    description: &#x22;The available height in the viewport for the toolbar to fit within, accounting for collision boundaries.&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 800px)&#x22;,
  },
  {
    title: &#x22;--selection-toolbar-anchor-width&#x22;,
    description: &#x22;The width of the selected text (anchor element).&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 150px)&#x22;,
  },
  {
    title: &#x22;--selection-toolbar-anchor-height&#x22;,
    description: &#x22;The height of the selected text (anchor element).&#x22;,
    defaultValue: &#x22;Dynamic (e.g., 24px)&#x22;,
  },
]"
/>

### SelectionToolbarItem [#selectiontoolbaritem]

An actionable item within the toolbar, typically containing an icon.

<AutoTypeTable path="./types/radix/selection-toolbar.ts" name="SelectionToolbarItemProps" />

### SelectionToolbarSeparator [#selectiontoolbarseparator]

A visual separator between toolbar items.

<AutoTypeTable path="./types/radix/selection-toolbar.ts" name="SelectionToolbarSeparatorProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the toolbar and clears the text selection.&#x22;,
  },
]"
/>


# Sortable
URL: /docs/components/radix/sortable



<ComponentTabs name="sortable-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/sortable

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/sortable

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/sortable

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/sortable

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="sortable" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Sortable,
  SortableContent,
  SortableItem,
  SortableItemHandle,
  SortableOverlay,
} from "@/components/ui/sortable";

return (
  <Sortable>
    <SortableContent>
      <SortableItem >
        <SortableItemHandle />
      </SortableItem>
      <SortableItem />
    </SortableContent>
    <SortableOverlay />
  </Sortable>
)
```

## Usage [#usage]

### With Primitive Values [#with-primitive-values]

When using primitive arrays (strings, numbers), the `getItemValue` prop is optional. The component will automatically use the item itself as the unique identifier.

```tsx
const [items, setItems] = React.useState(["Item 1", "Item 2", "Item 3"]);

<Sortable value={items} onValueChange={setItems}>
  <SortableContent>
    {items.map((item) => (
      <SortableItem key={item} value={item}>
        {item}
      </SortableItem>
    ))}
  </SortableContent>
</Sortable>
```

### With Object Arrays [#with-object-arrays]

When using object arrays, the `getItemValue` prop is required to extract a unique identifier from each item.

```tsx
const [items, setItems] = React.useState([
  { id: 1, name: "Item 1" },
  { id: 2, name: "Item 2" },
]);

<Sortable
  value={items}
  onValueChange={setItems}
  getItemValue={(item) => item.id}
>
  <SortableContent>
    {items.map((item) => (
      <SortableItem key={item.id} value={item.id}>
        {item.name}
      </SortableItem>
    ))}
  </SortableContent>
</Sortable>
```

## Examples [#examples]

### With Dynamic Overlay [#with-dynamic-overlay]

Display a dynamic overlay when an item is being dragged.

<ComponentTabs name="sortable-dynamic-overlay-demo" />

### With Handle [#with-handle]

Use `ItemHandle` as a drag handle for sortable items.

<ComponentTabs name="sortable-handle-demo" />

### With Primitive Values [#with-primitive-values-1]

Use an array of primitives (string or number) instead of objects for sorting.

<ComponentTabs name="sortable-primitive-values-demo" />

## API Reference [#api-reference]

### Sortable [#sortable]

The main container component for sortable functionality.

<AutoTypeTable path="./types/radix/sortable.ts" name="SortableProps" />

### SortableContent [#sortablecontent]

Container for sortable items. Multiple `SortableContent` components can be used within a `Sortable` component.

<AutoTypeTable path="./types/radix/sortable.ts" name="SortableContentProps" />

### SortableItem [#sortableitem]

Individual sortable item component.

<AutoTypeTable path="./types/radix/sortable.ts" name="SortableItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the item is being dragged.&#x22;,
  },
]"
/>

### SortableItemHandle [#sortableitemhandle]

A button component that acts as a drag handle for sortable items.

<AutoTypeTable path="./types/radix/sortable.ts" name="SortableItemHandleProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the item is disabled.&#x22;,
  },
  {
    title: &#x22;[data-dragging]&#x22;,
    value: &#x22;Present when the parent sortable item is being dragged.&#x22;,
  }
]"
/>

The component extends the base `Button` component and adds the following styles:

* `select-none` for pointer events
* `cursor-grab` when not dragging (unless `flatCursor` is true)
* `cursor-grabbing` when dragging (unless `flatCursor` is true)
* `cursor-default` when `flatCursor` is true

### Overlay [#overlay]

The overlay component that appears when an item is being dragged.

<AutoTypeTable path="./types/radix/sortable.ts" name="SortableOverlayProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Picks up the sortable item for reordering when released, and drops the item in its new position when pressed again.&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;Moves the sortable item up in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;Moves the sortable item down in vertical orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Moves the sortable item left in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Moves the sortable item right in horizontal orientation.&#x22;,
  },
  {
    keys: [&#x22;Esc&#x22;],
    description: &#x22;Cancels the sort operation and returns the item to its original position.&#x22;,
  },
]"
/>


# Speed Dial
URL: /docs/components/radix/speed-dial



<ComponentTabs name="speed-dial-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/speed-dial
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="speed-dial" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  SpeedDial,
  SpeedDialTrigger,
  SpeedDialContent,
  SpeedDialItem,
  SpeedDialLabel,
  SpeedDialAction,
} from "@/components/ui/speed-dial";

return (
  <SpeedDial>
    <SpeedDialTrigger />
    <SpeedDialContent>
      <SpeedDialItem>
        <SpeedDialLabel />
        <SpeedDialAction />
      </SpeedDialItem>
    </SpeedDialContent>
  </SpeedDial>
)
```

## Examples [#examples]

### With Labels [#with-labels]

Display visible labels next to each action button for better discoverability.

<ComponentTabs name="speed-dial-labels-demo" />

### Hover Mode [#hover-mode]

Set `activationMode="hover"` on the root component to open the speed dial when hovering over the trigger. The speed dial will automatically close when the mouse leaves. Use the `delay` prop to control how long to wait before the speed dial opens.

<ComponentTabs name="speed-dial-hover-demo" />

### Controlled State [#controlled-state]

Use the `open` and `onOpenChange` props to control the speed dial state programmatically.

<ComponentTabs name="speed-dial-controlled-demo" />

### Sides [#sides]

The speed dial can expand in different directions using the `side` prop.

<ComponentTabs name="speed-dial-side-demo" />

### Fixed Positioning [#fixed-positioning]

To position the speed dial at a fixed location in the viewport (e.g., bottom-right corner), apply positioning classes to the `SpeedDial` root component, not the trigger.

```tsx
<SpeedDial className="fixed right-4 bottom-4">
  <SpeedDialTrigger>
    <Plus />
  </SpeedDialTrigger>
  <SpeedDialContent>
    {/* actions */}
  </SpeedDialContent>
</SpeedDial>
```

<Callout type="warn">
  **Important:** Apply `fixed` positioning to the `SpeedDial` root, not the `SpeedDialTrigger`. This ensures the content stays aligned with the trigger.
</Callout>

**Why this matters:** The content uses `absolute` positioning relative to its parent. If you apply `fixed` to the trigger instead, the content won't be able to position itself correctly relative to the trigger.

```tsx
// ❌ Incorrect - content won't align properly
<SpeedDial>
  <SpeedDialTrigger className="fixed right-4 bottom-4">
    <Plus />
  </SpeedDialTrigger>
  <SpeedDialContent>
    {/* actions */}
  </SpeedDialContent>
</SpeedDial>

// ✅ Correct - content aligns with trigger
<SpeedDial className="fixed right-4 bottom-4">
  <SpeedDialTrigger>
    <Plus />
  </SpeedDialTrigger>
  <SpeedDialContent>
    {/* actions */}
  </SpeedDialContent>
</SpeedDial>
```

## API Reference [#api-reference]

### SpeedDial [#speeddial]

The main container component for the speed dial.

<AutoTypeTable path="./types/radix/speed-dial.ts" name="SpeedDialProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the speed dial is disabled.&#x22;,
  },
]"
/>

### SpeedDialTrigger [#speeddialtrigger]

The button that toggles the speed dial open/closed state.

<AutoTypeTable path="./types/radix/speed-dial.ts" name="SpeedDialTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### SpeedDialContent [#speeddialcontent]

The container for the action items that appears when the speed dial is open.

<AutoTypeTable path="./types/radix/speed-dial.ts" name="SpeedDialContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--speed-dial-gap&#x22;,
    description: &#x22;Gap between action items. Defaults to 0.5rem.&#x22;,
  },
  {
    title: &#x22;--speed-dial-offset&#x22;,
    description: &#x22;Offset distance from the trigger. Defaults to 0.5rem.&#x22;,
  },
  {
    title: &#x22;--speed-dial-transform-origin&#x22;,
    description: &#x22;Transform origin for animations based on the side.&#x22;,
  },
]"
/>

### SpeedDialItem [#speeddialitem]

A wrapper for each action and its associated label.

<AutoTypeTable path="./types/radix/speed-dial.ts" name="SpeedDialItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--speed-dial-animation-duration&#x22;,
    description: &#x22;Duration of the animation for item appearance. Defaults to 200ms.&#x22;,
  },
  {
    title: &#x22;--speed-dial-delay&#x22;,
    description: &#x22;Animation delay for staggered item appearance.&#x22;,
  },
  {
    title: &#x22;--speed-dial-transform-origin&#x22;,
    description: &#x22;Transform origin for item animations.&#x22;,
  },
]"
/>

### SpeedDialAction [#speeddialaction]

An interactive button within the speed dial that triggers an action.

<AutoTypeTable path="./types/radix/speed-dial.ts" name="SpeedDialActionProps" />

### SpeedDialLabel [#speeddiallabel]

A text label that describes the associated action.

<AutoTypeTable path="./types/radix/speed-dial.ts" name="SpeedDialLabelProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;When focus is on the trigger, toggles the speed dial open/closed.&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Closes the speed dial and returns focus to the trigger.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus between actions. Closes the speed dial when focus moves out.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous action. Closes the speed dial when focus moves out.&#x22;,
  },
]"
/>


# Stack
URL: /docs/components/radix/stack



<ComponentTabs name="stack-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/stack

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="stack" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import * as Stack from "@/components/ui/stack";

<Stack.Root>
  <Stack.Item />
</Stack.Root>
```

## Examples [#examples]

### Without Expansion [#without-expansion]

Disable the hover expansion effect for a static stack.

<ComponentTabs name="stack-no-expand-demo" />

### Different Sides [#different-sides]

Stack items from different sides using the `side` prop.

<ComponentTabs name="stack-side-demo" />

## API Reference [#api-reference]

### Stack.Root [#stackroot]

The main container component that manages layout and hover interactions.

<AutoTypeTable path="./types/radix/stack.ts" name="StackProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-expanded]&#x22;,
    value: [&#x22;true&#x22;, &#x22;false&#x22;],
  },
]"
/>

### Stack.Item [#stackitem]

Individual items within the stack. These are automatically positioned and animated.

<AutoTypeTable path="./types/radix/stack.ts" name="StackItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-index]&#x22;,
    value: [&#x22;number&#x22;],
  },
  {
    title: &#x22;[data-front]&#x22;,
    value: [&#x22;true&#x22;, &#x22;false&#x22;],
  },
  {
    title: &#x22;[data-visible]&#x22;,
    value: [&#x22;true&#x22;, &#x22;false&#x22;],
  },
]"
/>

## Features [#features]

* **Hover Expansion**: Items expand on hover to reveal all stacked items
* **Customizable**: Control visible items, gap, offset, and scale factor
* **Smooth Animations**: Elegant CSS transitions for all interactions
* **Flexible Styling**: Works with any content and styling approach
* **Accessibility**: Proper data attributes and semantic HTML

## Usage Notes [#usage-notes]

* The stack uses absolute positioning for items, ensure the parent container has enough space
* Use the `visibleItems` prop to control how many items are visible in the collapsed state
* The `scaleFactor` prop determines how much each subsequent item shrinks (0.05 = 5% smaller)
* Set `expandOnHover={false}` to disable the expansion effect
* All items beyond `visibleItems` will have reduced opacity and be non-interactive when collapsed

## Credits [#credits]

* [Emil Kowalski](https://emilkowal.ski/) - For the [Sonner](https://github.com/emilkowalski/sonner) toast library.


# Stat
URL: /docs/components/radix/stat



<ComponentTabs name="stat-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/stat
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="stat" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Stat,
  StatLabel,
  StatValue,
  StatIndicator,
  StatTrend,
  StatDescription,
  StatSeparator,
} from "@/components/ui/stat";

return (
  <Stat>
    <StatLabel>Total Revenue</StatLabel>
    <StatIndicator variant="icon" color="success">
      <DollarSign />
    </StatIndicator>
    <StatValue>$45,231</StatValue>
    <StatTrend trend="up">
      <ArrowUp />
      +20.1% from last month
    </StatTrend>
    <StatSeparator />
    <StatDescription>
      Total revenue generated in the current billing period
    </StatDescription>
  </Stat>
);
```

## Examples [#examples]

### Variants [#variants]

Explore different indicator variants and color themes.

<ComponentTabs name="stat-variants-demo" />

### Layout Options [#layout-options]

Combine different stat components to create rich statistical displays.

<ComponentTabs name="stat-layout-demo" />

## API Reference [#api-reference]

### Stat [#stat]

The main container component that provides a card-style layout for displaying statistics.

<AutoTypeTable path="./types/radix/stat.ts" name="StatProps" />

### StatLabel [#statlabel]

A label component for the statistic title or category.

<AutoTypeTable path="./types/radix/stat.ts" name="StatLabelProps" />

### StatIndicator [#statindicator]

A visual indicator component that can display icons, badges, or action buttons with various color themes.

<AutoTypeTable path="./types/radix/stat.ts" name="StatIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;default&#x22;, &#x22;icon&#x22;, &#x22;badge&#x22;, &#x22;action&#x22;],
  },
  {
    title: &#x22;[data-color]&#x22;,
    value: [&#x22;default&#x22;, &#x22;success&#x22;, &#x22;info&#x22;, &#x22;warning&#x22;, &#x22;error&#x22;],
  },
]"
/>

### StatValue [#statvalue]

Displays the primary statistic value with emphasized typography.

<AutoTypeTable path="./types/radix/stat.ts" name="StatValueProps" />

### StatTrend [#stattrend]

Displays trend information with directional styling (up, down, or neutral).

<AutoTypeTable path="./types/radix/stat.ts" name="StatTrendProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-trend]&#x22;,
    value: [&#x22;up&#x22;, &#x22;down&#x22;, &#x22;neutral&#x22;],
  },
]"
/>

### StatSeparator [#statseparator]

A horizontal separator for dividing content within the stat card.

<AutoTypeTable path="./types/radix/stat.ts" name="StatSeparatorProps" />

### StatDescription [#statdescription]

Additional descriptive text for providing context about the stat.


# Status
URL: /docs/components/radix/status



<ComponentTabs name="status-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/status
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="status" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Status,
  StatusIndicator,
  StatusLabel,
} from "@/components/ui/status";

return (
  <Status variant="success">
    <StatusIndicator />
    <StatusLabel>Online</StatusLabel>
  </Status>
);
```

## Examples [#examples]

### Variants [#variants]

Status supports five color variants to represent different states.

<ComponentTabs name="status-variants-demo" />

### Text Only [#text-only]

Use status without the indicator for a simpler appearance.

<ComponentTabs name="status-text-only-demo" />

### Service Status List [#service-status-list]

Display multiple status items in a list format, ideal for system health dashboards.

<ComponentTabs name="status-list-demo" />

## API Reference [#api-reference]

### Status [#status]

The main container component that provides the badge-style wrapper with color variants.

<AutoTypeTable path="./types/radix/status.ts" name="StatusProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;default&#x22;, &#x22;success&#x22;, &#x22;error&#x22;, &#x22;warning&#x22;, &#x22;info&#x22;],
  },
]"
/>

### StatusIndicator [#statusindicator]

An animated pulse indicator for the status.

<AutoTypeTable path="./types/radix/status.ts" name="StatusIndicatorProps" />

### StatusLabel [#statuslabel]

The text label for the status.

<AutoTypeTable path="./types/radix/status.ts" name="StatusLabelProps" />

## Accessibility [#accessibility]

The Status component uses semantic HTML and follows best practices for accessibility:

* Uses `div` elements with proper ARIA attributes when needed
* Color is not the only means of conveying information—always include text labels
* Supports keyboard navigation when used with interactive elements via `asChild`

## Notes [#notes]

* The animated ping effect uses Tailwind's built-in `animate-ping` utility for smooth performance
* Colors automatically adapt to dark mode
* The indicator animation runs continuously to draw attention to live status changes
* Use the `asChild` prop to render Status as a link or button for interactive use cases


# Stepper
URL: /docs/components/radix/stepper



<ComponentTabs name="stepper-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/stepper

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="stepper" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Stepper,
  StepperList,
  StepperItem,
  StepperTrigger,
  StepperIndicator,
  StepperTitle,
  StepperDescription,
  StepperSeparator,
  StepperContent,
  StepperPrev,
  StepperNext,
} from "@/components/ui/stepper";

return (
  <Stepper>
    <StepperList>
      <StepperItem>
        <StepperTrigger>
          <StepperIndicator />
          <StepperTitle />
          <StepperDescription />
        </StepperTrigger>
        <StepperSeparator />
      </StepperItem>
    </StepperList>
    <StepperContent />
    <StepperPrev /> 
    <StepperNext />
  </Stepper>
)
```

## Examples [#examples]

### Vertical Layout [#vertical-layout]

A stepper with vertical orientation for compact layouts.

<ComponentTabs name="stepper-vertical-demo" />

### With Validation [#with-validation]

Use the `onValidate` prop to validate the current step before moving to the next one.

<ComponentTabs name="stepper-validation-demo" />

### With Form [#with-form]

A stepper integrated with form validation, showing step-by-step form completion.

<ComponentTabs name="stepper-form-demo" />

## API Reference [#api-reference]

### Stepper [#stepper]

The main container component for the stepper.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### StepperList [#stepperlist]

The container for stepper items, typically an ordered list.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperListProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
]"
/>

### StepperItem [#stepperitem]

A single step item in the stepper.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperTrigger [#steppertrigger]

The clickable trigger for each step, typically wrapping the indicator.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperIndicator [#stepperindicator]

The visual indicator showing the step number or completion status.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperIndicatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperSeparator [#stepperseparator]

The line connecting steps, showing progress between them.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperSeparatorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;horizontal&#x22;, &#x22;vertical&#x22;],
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;inactive&#x22;, &#x22;active&#x22;, &#x22;completed&#x22;],
  },
]"
/>

### StepperTitle [#steppertitle]

The title text for each step.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperTitleProps" />

### StepperDescription [#stepperdescription]

The description text for each step.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperDescriptionProps" />

### StepperContent [#steppercontent]

The content area that displays for the active step.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperContentProps" />

### StepperPrev [#stepperprev]

A navigation button that moves to the previous step. Automatically disabled on the first step and skips validation when navigating backwards.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperPrevProps" />

### StepperNext [#steppernext]

A navigation button that moves to the next step. Automatically disabled on the last step and respects validation rules when navigating forwards.

<AutoTypeTable path="./types/radix/stepper.ts" name="StepperNextProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element.&#x22;,
  },
  {
    keys: [&#x22;Shift + Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Activates the focused step when clickable is enabled.&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;, &#x22;ArrowUp&#x22;],
    description: &#x22;Moves focus to the previous step trigger.&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;, &#x22;ArrowDown&#x22;],
    description: &#x22;Moves focus to the next step trigger.&#x22;,
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Moves focus to the first step trigger.&#x22;,
  },
  {
    keys: [&#x22;End&#x22;],
    description: &#x22;Moves focus to the last step trigger.&#x22;,
  },
]"
/>


# Swap
URL: /docs/components/radix/swap



<ComponentTabs name="swap-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/swap
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-value-as-ref" />

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="swap" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import { Swap, SwapOn, SwapOff } from "@/components/ui/swap";

return (
  <Swap>
    <SwapOn />
    <SwapOff />
  </Swap>
)
```

## Examples [#examples]

### Animations [#animations]

The swap component supports 4 different animation types: fade, rotate, flip, and scale.

<ComponentTabs name="swap-animations-demo" />

## API Reference [#api-reference]

### Swap [#swap]

The main container component for swap functionality.

<AutoTypeTable path="./types/radix/swap.ts" name="SwapProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
  {
    title: &#x22;[data-animation]&#x22;,
    value: [&#x22;fade&#x22;, &#x22;rotate&#x22;, &#x22;flip&#x22;, &#x22;scale&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the swap is disabled&#x22;,
  },
]"
/>

### SwapOn [#swapon]

The content shown when the swap is in the swapped state.

<AutoTypeTable path="./types/radix/swap.ts" name="SwapOnProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

### SwapOff [#swapoff]

The content shown when the swap is in the default state.

<AutoTypeTable path="./types/radix/swap.ts" name="SwapOffProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;on&#x22;, &#x22;off&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Toggles the swap state when activation mode is 'click'.&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;Toggles the swap state when activation mode is 'click'.&#x22;,
  },
]"
/>


# Tags Input
URL: /docs/components/radix/tags-input



<ComponentTabs name="tags-input-demo" />

## Installation [#installation]

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @diceui/tags-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @diceui/tags-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @diceui/tags-input
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @diceui/tags-input
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Installation with shadcn/ui [#installation-with-shadcnui]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/tags-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/tags-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/tags-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/tags-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/tags-input
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="tags-input" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  TagsInput,
  TagsInputLabel,
  TagsInputItem,
  TagsInputItemText,
  TagsInputItemDelete,
  TagsInputInput,
  TagsInputClear,
} from "@diceui/tags-input";

return (
  <TagsInput>
    <TagsInputLabel/>
    <TagsInputItem >
      <TagsInputItemText />
      <TagsInputItemDelete />
    </TagsInputItem>
    <TagsInputInput />
    <TagsInputClear />
  </TagsInput>
)
```

## Examples [#examples]

### Editable [#editable]

<ComponentTabs name="tags-input-editable-demo" />

### With Validation [#with-validation]

Validate the input value before adding it to the list. Can be used to prevent duplicate tags.

<ComponentTabs name="tags-input-validation-demo" />

### With Sortable [#with-sortable]

`TagsInput` can be composed with [`Sortable`](/docs/components/radix/sortable) to allow reordering of tags.

<ComponentTabs name="tags-input-sortable-demo" />

## API Reference [#api-reference]

### TagsInput [#tagsinput]

Container for the tags input.

<AutoTypeTable path="./types/radix/tags-input.ts" name="RootProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when readOnly.&#x22;,
  },
]"
/>

### TagsInputLabel [#tagsinputlabel]

Label element for the tags input.

<AutoTypeTable path="./types/radix/tags-input.ts" name="LabelProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
]"
/>

### TagsInputInput [#tagsinputinput]

Text input for adding new tags.

<AutoTypeTable path="./types/radix/tags-input.ts" name="InputProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when invalid.&#x22;,
  },
]"
/>

### TagsInputItem [#tagsinputitem]

Individual tag item.

<AutoTypeTable path="./types/radix/tags-input.ts" name="ItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
  {
    title: &#x22;[data-highlighted]&#x22;,
    value: &#x22;Present when highlighted.&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-editing]&#x22;,
    value: &#x22;Present when being edited.&#x22;,
  },
  {
    title: &#x22;[data-editable]&#x22;,
    value: &#x22;Present when the tags input is editable.&#x22;,
  },
]"
/>

### TagsInputItemText [#tagsinputitemtext]

Text content of a tag.

<AutoTypeTable path="./types/radix/tags-input.ts" name="ItemTextProps" />

### TagsInputItemDelete [#tagsinputitemdelete]

Button to remove a tag.

<AutoTypeTable path="./types/radix/tags-input.ts" name="ItemDeleteProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;active&#x22;, &#x22;inactive&#x22;],
  },
]"
/>

### TagsInputClear [#tagsinputclear]

Button to clear all tags.

<AutoTypeTable path="./types/radix/tags-input.ts" name="ClearProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when disabled.&#x22;,
  },
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;visible&#x22;, &#x22;invisible&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Delete&#x22;],
    description: &#x22;When a tag is highlighted, removes it and sets focus to the next tag.&#x22;
  },
  {
    keys: [&#x22;Backspace&#x22;],
    description: &#x22;When a tag is highlighted, removes it and sets focus to the previous tag. If there is no previous tag, focus moves to the next tag or input.&#x22;
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;Highlights the previous tag. When cursor is at start of input, moves focus to the last tag.&#x22;
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;Highlights the next tag. When cursor is at start of input, moves focus to the first tag.&#x22;
  },
  {
    keys: [&#x22;Home&#x22;],
    description: &#x22;Highlights the first tag in the list.&#x22;
  },
  {
    keys: [&#x22;End&#x22;], 
    description: &#x22;Highlights the last tag in the list.&#x22;
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When input has text, adds a new tag. When a tag is highlighted and editable is enabled, enters edit mode.&#x22;
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Clears tag highlight and edit mode, resets cursor to start.&#x22;
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;When `addOnTab` is enabled and input has text, adds a new tag. Otherwise, blurs the input.&#x22;
  }
]"
/>


# Time Picker
URL: /docs/components/radix/time-picker



<ComponentTabs name="time-picker-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/time-picker
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the visually hidden input component into your 

        `components/visually-hidden-input.tsx`

         file.
      </Step>

      <ComponentSource name="visually-hidden-input" />

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="time-picker" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  TimePicker,
  TimePickerLabel,
  TimePickerInputGroup,
  TimePickerInput,
  TimePickerSeparator,
  TimePickerTrigger,
  TimePickerContent,
  TimePickerHour,
  TimePickerMinute,
  TimePickerClear,
} from "@/components/ui/time-picker";

return (
  <TimePicker>
    <TimePickerLabel />
    <TimePickerInputGroup>
      <TimePickerInput segment="hour" />
      <TimePickerSeparator />
      <TimePickerInput segment="minute" />
      <TimePickerInput segment="period" />
      <TimePickerTrigger />
    </TimePickerInputGroup>
    <TimePickerContent>
      <TimePickerHour />
      <TimePickerMinute />
      <TimePickerClear />
    </TimePickerContent>
  </TimePicker>
)
```

## Examples [#examples]

### With Step [#with-step]

Use the `hourStep`, `minuteStep`, and `secondStep` props to set custom intervals for hour, minute, and second selection respectively.

<ComponentTabs name="time-picker-step-demo" />

### With Seconds [#with-seconds]

Include seconds in time selection.

<ComponentTabs name="time-picker-seconds-demo" />

### Custom Placeholders [#custom-placeholders]

Customize empty segment placeholders for different display formats.

<ComponentTabs name="time-picker-placeholder-demo" />

### Open on Focus [#open-on-focus]

Use the `openOnFocus` prop to open the content when the input is focused.

<ComponentTabs name="time-picker-open-on-focus-demo" />

### Input Group Click Action [#input-group-click-action]

Configure what happens when clicking on empty space in the input group. By default, it focuses the first input for inline editing, but you can set it to open the popover instead.

<ComponentTabs name="time-picker-input-group-click-action-demo" />

### Controlled State [#controlled-state]

Control the time picker value programmatically.

<ComponentTabs name="time-picker-controlled-demo" />

### With Form [#with-form]

Use the time picker in a form with validation.

<ComponentTabs name="time-picker-form-demo" />

## API Reference [#api-reference]

### TimePicker [#timepicker]

The main container component for time picker functionality.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the time picker is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the time picker is invalid&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the time picker is read-only&#x22;,
  },
]"
/>

### TimePickerLabel [#timepickerlabel]

The label component for the time picker field.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerLabelProps" />

### TimePickerInputGroup [#timepickerinputgroup]

The container for input segments that sets up CSS variables for dynamic segment widths.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerInputGroupProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the time picker is disabled&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the time picker is invalid&#x22;,
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--time-picker-hour-input-width&#x22;,
    description: &#x22;The width of the hour input segment, dynamically calculated based on the hour placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
  {
    title: &#x22;--time-picker-minute-input-width&#x22;,
    description: &#x22;The width of the minute input segment, dynamically calculated based on the minute placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
  {
    title: &#x22;--time-picker-second-input-width&#x22;,
    description: &#x22;The width of the second input segment, dynamically calculated based on the second placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
  {
    title: &#x22;--time-picker-period-input-width&#x22;,
    description: &#x22;The width of the period (AM/PM) input segment, dynamically calculated based on the period placeholder length.&#x22;,
    defaultValue: &#x22;2ch (for '--' placeholder)&#x22;,
  },
]"
/>

Must use style prop to override the css variables of the input segment, because the width is dynamically calculated based on the placeholder length.

### TimePickerTrigger [#timepickertrigger]

Button to open the time picker content.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerTriggerProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: &#x22;'open' | 'closed'&#x22;,
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: &#x22;Present when the time picker is disabled&#x22;,
  },
  {
    title: &#x22;[data-readonly]&#x22;,
    value: &#x22;Present when the time picker is read-only&#x22;,
  },
  {
    title: &#x22;[data-invalid]&#x22;,
    value: &#x22;Present when the time picker is invalid&#x22;,
  },
]"
/>

### TimePickerContent [#timepickercontent]

Container for the time selection interface.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-state]&#x22;,
    value: &#x22;'open' | 'closed'&#x22;,
  },
  {
    title: &#x22;[data-side]&#x22;,
    value: &#x22;The side where the content is positioned&#x22;,
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: &#x22;The alignment of the content&#x22;,
  },
]"
/>

### TimePickerHour [#timepickerhour]

Component for selecting hours.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerHourProps" />

### TimePickerMinute [#timepickerminute]

Component for selecting minutes.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerMinuteProps" />

### TimePickerSecond [#timepickersecond]

Component for selecting seconds.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerSecondProps" />

### TimePickerPeriod [#timepickerperiod]

Component for selecting AM/PM in 12-hour format.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerPeriodProps" />

### TimePickerSeparator [#timepickerseparator]

Visual separator between time units.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerSeparatorProps" />

### TimePickerClear [#timepickerclear]

Button to clear the selected time.

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerClearProps" />

### TimePickerInput [#timepickerinput]

Inline editable input field for time segments (hour, minute, second, period).

<AutoTypeTable path="./types/radix/time-picker.ts" name="TimePickerInputProps" />

<CSSVariablesTable
  data="[
  {
    title: &#x22;--time-picker-hour-input-width&#x22;,
    description: &#x22;Can be set directly on the hour segment input to override the width for that specific input.&#x22;,
  },
  {
    title: &#x22;--time-picker-minute-input-width&#x22;,
    description: &#x22;Can be set directly on the minute segment input to override the width for that specific input.&#x22;,
  },
  {
    title: &#x22;--time-picker-second-input-width&#x22;,
    description: &#x22;Can be set directly on the second segment input to override the width for that specific input.&#x22;,
  },
  {
    title: &#x22;--time-picker-period-input-width&#x22;,
    description: &#x22;Can be set directly on the period segment input to override the width for that specific input.&#x22;,
  },
]"
/>

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;0-9&#x22;],
    description: &#x22;Type digits to enter time values in input segments. Auto-pads single digits (1 → 01) and auto-advances to next segment after two digits or when first digit exceeds maximum&#x22;,
  },
  {
    keys: [&#x22;A&#x22;, &#x22;1&#x22;],
    description: &#x22;Sets period to AM when period input is focused&#x22;,
  },
  {
    keys: [&#x22;P&#x22;, &#x22;2&#x22;],
    description: &#x22;Sets period to PM when period input is focused&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;When the input is focused, moves to next segment (hour → minute → second → period). When the content is open, moves to next column with wrapping&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;When the input is focused, moves to previous segment. When the content is open, moves to previous column with wrapping&#x22;,
  },
  {
    keys: [&#x22;ArrowRight&#x22;],
    description: &#x22;When the input is focused, moves to next segment. When the content is open, moves to next column with wrapping&#x22;,
  },
  {
    keys: [&#x22;ArrowLeft&#x22;],
    description: &#x22;When the input is focused, moves to previous segment. When the content is open, moves to previous column with wrapping&#x22;,
  },
  {
    keys: [&#x22;ArrowUp&#x22;],
    description: &#x22;When the input is focused, increments value with wrapping, selection preserved. When the content is open, navigates to previous value in column&#x22;,
  },
  {
    keys: [&#x22;ArrowDown&#x22;],
    description: &#x22;When the input is focused, decrements value with wrapping, selection preserved. When the content is open, navigates to next value in column&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;When the input is focused, confirms and removes focus. When the content is open, selects highlighted value. When the trigger is focused, opens/closes the content&#x22;,
  },
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;When the input is focused, cancels editing and restores previous value. When the content is open, closes without changing value&#x22;,
  },
  {
    keys: [&#x22;Space&#x22;],
    description: &#x22;When the trigger is focused, opens/closes the content&#x22;,
  },
  {
    keys: [&#x22;Backspace&#x22;, &#x22;Delete&#x22;],
    description: &#x22;Clears focused segment back to placeholder (--) when entire segment is selected&#x22;,
  },
]"
/>

## Notes [#notes]

### Behavior [#behavior]

* **Native HTML time input behavior**: Replicates the exact behavior of `<input type="time">` for maximum familiarity
  * Auto-pads single digits instantly (typing "1" shows "01")
  * Smart auto-advance after two digits or when digit exceeds maximum first digit
  * Partial time values supported (e.g., "10:--" instead of "10:00")
  * Selection preserved after actions for seamless typing
* **Inline editing**: All time segments are always visible and editable, no need to open the content
* **Content for convenience**: The clock icon trigger opens the content for easier selection with mouse/touch
* **Keyboard-first design**: Full keyboard navigation between segments using arrow keys or tab
* **Clear segments**: Press Backspace or Delete on a selected segment to clear it back to "--"

### Format & Locale [#format--locale]

* **Automatic format detection**: Display format (12-hour vs 24-hour) is automatically detected from user's locale settings
* **Consistent value format**: The time value is always stored in 24-hour format ("HH:mm" or "HH:mm:ss"), regardless of display format
* **Locale override**: Use the `locale` prop to explicitly set a locale (e.g., "en-US" for 12-hour, "en-GB" for 24-hour)
* **Period shortcuts**: In 12-hour format, use A/P or 1/2 keys to quickly set AM/PM


# Timeline
URL: /docs/components/radix/timeline



<ComponentTabs name="timeline-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/timeline

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="timeline" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

```tsx
import {
  Timeline,
  TimelineItem,
  TimelineDot,
  TimelineConnector,
  TimelineContent,
  TimelineHeader,
  TimelineTitle,
  TimelineTime,
  TimelineDescription,
} from "@/components/ui/timeline";

<Timeline>
  <TimelineItem>
    <TimelineDot />
    <TimelineConnector />
    <TimelineContent>
      <TimelineHeader>
        <TimelineTitle />
        <TimelineTime />
      </TimelineHeader>
      <TimelineDescription />
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

## Examples [#examples]

### Horizontal Timeline [#horizontal-timeline]

Display timeline events horizontally across the screen.

<ComponentTabs name="timeline-horizontal-demo" />

### RTL Timeline [#rtl-timeline]

Display timeline with right-to-left layout for RTL languages.

<ComponentTabs name="timeline-rtl-demo" />

### Alternate Timeline [#alternate-timeline]

Display timeline events in an alternating pattern with content on both sides.

<ComponentTabs name="timeline-alternate-demo" />

### Horizontal Alternate Timeline [#horizontal-alternate-timeline]

Display timeline events horizontally with content alternating above and below.

<ComponentTabs name="timeline-horizontal-alternate-demo" />

### With Custom Dots [#with-custom-dots]

Add custom icons or content to the timeline dots using CSS variables.

<ComponentTabs name="timeline-custom-dot-demo" />

## API Reference [#api-reference]

### Timeline [#timeline]

The root container for timeline items.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
  {
    title: &#x22;[data-variant]&#x22;,
    value: [&#x22;default&#x22;, &#x22;alternate&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--timeline-dot-size&#x22;,
    description: &#x22;The size (width and height) of the timeline dot marker.&#x22;,
    defaultValue: &#x22;0.875rem (14px)&#x22;,
  },
  {
    title: &#x22;--timeline-connector-thickness&#x22;,
    description: &#x22;The thickness of the timeline connector line.&#x22;,
    defaultValue: &#x22;0.125rem (2px)&#x22;,
  },
]"
/>

### TimelineItem [#timelineitem]

A single timeline item containing content, marker, and connector.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineItemProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
  {
    title: &#x22;[data-alternate-right]&#x22;,
    value: [&#x22;Present when item is on the right/bottom in alternate variant&#x22;],
  },
]"
/>

### TimelineDot [#timelinedot]

The visual marker/dot for a timeline item.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineDotProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--timeline-dot-size&#x22;,
    description: &#x22;The size (width and height) of the timeline dot marker.&#x22;,
    defaultValue: &#x22;0.875rem (14px)&#x22;,
  },
]"
/>

### TimelineConnector [#timelineconnector]

The line connecting timeline items.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineConnectorProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-completed]&#x22;,
    value: [&#x22;Present when connector represents a completed transition&#x22;],
  },
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
  {
    title: &#x22;[data-orientation]&#x22;,
    value: [&#x22;vertical&#x22;, &#x22;horizontal&#x22;],
  },
]"
/>

<CSSVariablesTable
  data="[
  {
    title: &#x22;--timeline-connector-thickness&#x22;,
    description: &#x22;The thickness of the timeline connector line.&#x22;,
    defaultValue: &#x22;0.125rem (2px)&#x22;,
  },
]"
/>

### TimelineHeader [#timelineheader]

Container for the title and time of a timeline item.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineHeaderProps" />

### TimelineTitle [#timelinetitle]

The title/heading of a timeline item.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineTitleProps" />

### TimelineDescription [#timelinedescription]

The description/body text of a timeline item.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineDescriptionProps" />

### TimelineContent [#timelinecontent]

Container for the timeline item's content (header, description, etc.).

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineContentProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-status]&#x22;,
    value: [&#x22;completed&#x22;, &#x22;active&#x22;, &#x22;pending&#x22;],
  },
]"
/>

### TimelineTime [#timelinetime]

A semantic time element for displaying dates/times.

<AutoTypeTable path="./types/radix/timeline.ts" name="TimelineTimeProps" />

## Features [#features]

### Flexible Orientations [#flexible-orientations]

The timeline supports both vertical and horizontal orientations. Use the `orientation` prop on `Timeline.Root` to switch between layouts.

### Alternate Variant [#alternate-variant]

The timeline supports an alternate variant where content alternates on both sides of the timeline. Use the `variant="alternate"` prop on `Timeline.Root` to enable this layout. This works with both vertical and horizontal orientations:

* **Vertical alternate**: Content alternates left and right of the center line
* **Horizontal alternate**: Content alternates above and below the center line

```tsx
<Timeline.Root variant="alternate" orientation="horizontal">
  {/* Content alternates above and below */}
</Timeline.Root>
```

### RTL Support [#rtl-support]

The timeline fully supports right-to-left (RTL) layouts through the `dir` prop. When set to `"rtl"`, the timeline automatically flips its layout direction, making it ideal for RTL languages like Arabic, Hebrew, and Persian.

### Active Index [#active-index]

Control the visual state of timeline items using the `activeIndex` prop on the root component. Items before the active index will be marked as "completed", the item at the active index will be "active", and items after will be "pending".

```tsx
<Timeline.Root activeIndex={2}>
  <Timeline.Item>Step 1 - Completed</Timeline.Item>
  <Timeline.Item>Step 2 - Completed</Timeline.Item>
  <Timeline.Item>Step 3 - Active (index 2)</Timeline.Item>
  <Timeline.Item>Step 4 - Pending</Timeline.Item>
</Timeline.Root>
```

The `activeIndex` is zero-based, so `activeIndex={2}` makes the third item active.

### Custom Icons [#custom-icons]

Replace the default dot marker with custom icons or React components by passing children to `Timeline.Dot`, giving you full control over the visual appearance.

### Composition Pattern [#composition-pattern]

Built with a composable API that gives you complete control over the structure and styling of your timeline. Mix and match components as needed.

## Accessibility [#accessibility]

### ARIA Roles [#aria-roles]

The timeline uses ARIA roles and attributes for proper accessibility:

* Root uses `role="list"` and `aria-orientation` to represent an ordered list of events
* Each item uses `role="listitem"` for proper list semantics
* Active items use `aria-current="step"` to indicate current position in the timeline
* Semantic `<time>` elements with `dateTime` attribute for proper date representation
* Connectors are marked with `aria-hidden="true"` as they're purely decorative


# Tour
URL: /docs/components/radix/tour



<ComponentTabs name="tour-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/tour

        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @floating-ui/react-dom radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following hooks into your 

        `hooks`

         directory.
      </Step>

      <ComponentSource name="use-ref-with-init" />

      <ComponentSource name="use-value-as-ref" />

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="tour" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the parts, and compose them together.

```tsx
import {
  Tour,
  TourPortal,
  TourSpotlight,
  TourSpotlightRing,
  TourStep,
  TourArrow,
  TourClose,
  TourHeader,
  TourTitle,
  TourDescription,
  TourFooter,
  TourStepCounter,
  TourPrev,
  TourNext,
  TourSkip,
} from "@/components/ui/tour";

return (
  <Tour>
    <TourPortal>
      <TourSpotlight />
      <TourSpotlightRing />
      <TourStep>
        <TourArrow />
        <TourClose />
        <TourHeader>
          <TourTitle />
          <TourDescription />
        </TourHeader>
        <TourFooter>
          <TourStepCounter />
          <TourPrev />
          <TourNext />
          <TourSkip />
        </TourFooter>
      </TourStep>
    </TourPortal>
  </Tour>
)
```

## Examples [#examples]

### Controlled [#controlled]

A tour with controlled state management, allowing external control of the current step.

<ComponentTabs name="tour-controlled-demo" />

### Custom Spotlight Styling [#custom-spotlight-styling]

You can customize the appearance of the spotlighted element using the `SpotlightRing` component:

```tsx
<Tour.Root open={open} onOpenChange={setOpen}>
  <Tour.Portal>
    <Tour.Spotlight />
    {/* Border style */}
    <Tour.SpotlightRing className="rounded-lg border-2 border-primary" />
    {/* Ring with offset */}
    <Tour.SpotlightRing className="rounded-xl ring-2 ring-blue-500 ring-offset-2" />
    {/* Glowing effect */}
    <Tour.SpotlightRing className="rounded-lg shadow-lg shadow-primary/50" />
    {/* Animated pulse */}
    <Tour.SpotlightRing className="rounded-lg border-2 border-primary animate-pulse" />
    <Tour.Step target="#element">{/* ... */}</Tour.Step>
  </Tour.Portal>
</Tour.Root>
```

### Global Offset Control [#global-offset-control]

Set default spacing for all steps and override per step:

```tsx
<Tour.Root
  open={open}
  onOpenChange={setOpen}
  sideOffset={16}      // Global default: 16px gap
  alignOffset={0}      // Global alignment offset
>
  <Tour.Portal>
    <Tour.Spotlight />
    <Tour.SpotlightRing />
    
    {/* Uses global sideOffset={16} */}
    <Tour.Step target="#step-1" side="bottom">
      <Tour.Header>
        <Tour.Title>Step 1</Tour.Title>
      </Tour.Header>
    </Tour.Step>
    
    {/* Overrides with custom sideOffset={32} */}
    <Tour.Step target="#step-2" side="top" sideOffset={32}>
      <Tour.Header>
        <Tour.Title>Step 2 - Larger Gap</Tour.Title>
      </Tour.Header>
    </Tour.Step>
  </Tour.Portal>
</Tour.Root>
```

## API Reference [#api-reference]

### Tour [#tour]

The main container component for the tour that manages state and provides context.

<AutoTypeTable path="./types/radix/tour.ts" name="TourProps" />

### TourSpotlight [#tourspotlight]

The spotlight backdrop that dims the page and highlights the target element with a cutout effect.

<AutoTypeTable path="./types/radix/tour.ts" name="TourSpotlightProps" />

<DataAttributesTable
  attributes="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### TourSpotlightRing [#tourspotlightring]

A visual ring/border element that wraps around the spotlighted target element. Use this to add custom styling like borders, shadows, or animations to the highlighted area.

<AutoTypeTable path="./types/radix/tour.ts" name="TourSpotlightRingProps" />

<DataAttributesTable
  attributes="[
  {
    title: &#x22;[data-state]&#x22;,
    value: [&#x22;open&#x22;, &#x22;closed&#x22;],
  },
]"
/>

### TourStep [#tourstep]

A single step in the tour that targets a specific element on the page.

<AutoTypeTable path="./types/radix/tour.ts" name="TourStepProps" />

<DataAttributesTable
  attributes="[
  {
    title: &#x22;[data-side]&#x22;,
    value: [&#x22;top&#x22;, &#x22;right&#x22;, &#x22;bottom&#x22;, &#x22;left&#x22;],
  },
  {
    title: &#x22;[data-align]&#x22;,
    value: [&#x22;start&#x22;, &#x22;center&#x22;, &#x22;end&#x22;],
  },
]"
/>

### TourClose [#tourclose]

Button to close the entire tour.

<AutoTypeTable path="./types/radix/tour.ts" name="TourCloseProps" />

### TourHeader [#tourheader]

Container for the tour step's title and description.

<AutoTypeTable path="./types/radix/tour.ts" name="TourHeaderProps" />

### TourTitle [#tourtitle]

The title of the current tour step.

<AutoTypeTable path="./types/radix/tour.ts" name="TourTitleProps" />

### TourDescription [#tourdescription]

The description text for the current tour step.

<AutoTypeTable path="./types/radix/tour.ts" name="TourDescriptionProps" />

### TourFooter [#tourfooter]

Container for tour navigation controls and step counter.

<AutoTypeTable path="./types/radix/tour.ts" name="TourFooterProps" />

### TourStepCounter [#tourstepcounter]

Displays the current step number and total steps.

<AutoTypeTable path="./types/radix/tour.ts" name="TourStepCounterProps" />

### TourPrev [#tourprev]

Button to navigate to the previous step.

<AutoTypeTable path="./types/radix/tour.ts" name="TourPrevProps" />

### TourNext [#tournext]

Button to navigate to the next step or complete the tour.

<AutoTypeTable path="./types/radix/tour.ts" name="TourNextProps" />

### TourSkip [#tourskip]

Button to skip the entire tour.

<AutoTypeTable path="./types/radix/tour.ts" name="TourSkipProps" />

### TourArrow [#tourarrow]

An optional arrow element that points to the target element.

<AutoTypeTable path="./types/radix/tour.ts" name="TourArrowProps" />

## Accessibility [#accessibility]

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Escape&#x22;],
    description: &#x22;Triggers the onEscapeKeyDown callback. Default behavior closes the tour unless prevented.&#x22;,
  },
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Moves focus to the next focusable element within the tour content.&#x22;,
  },
  {
    keys: [&#x22;Shift&#x22;, &#x22;Tab&#x22;],
    description: &#x22;Moves focus to the previous focusable element within the tour content.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;, &#x22;Space&#x22;],
    description: &#x22;Activates the focused button (next, previous, skip, or close).&#x22;,
  },
]"
/>

## Credits [#credits]

* [Radix UI Dismissable Layer](https://github.com/radix-ui/primitives/blob/main/packages/react/dismissable-layer/src/dismissable-layer.tsx) - For the pointer down outside and interact outside event handling patterns.
* [Radix UI Focus Guard](https://github.com/radix-ui/primitives/blob/main/packages/react/focus-guards/src/focus-guards.tsx) - For the focus guard implementation.
* [Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog) - For the focus trap and auto-focus management patterns.


# Client Only
URL: /docs/utilities/base/client-only



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/client-only.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { ClientOnly } from "@/components/client-only"

export default function App() {
  return (
    <ClientOnly fallback={<LoadingSpinner />}>
      <ClientComponent />
    </ClientOnly>
  )
}
```

## API Reference [#api-reference]

### ClientOnly [#clientonly]

A component that only renders its children on the client side.

<AutoTypeTable path="./types/base/utilities.ts" name="ClientOnlyProps" />


# Composition
URL: /docs/utilities/base/composition



Dice UI's Base UI components follow [Base UI's composition model](https://base-ui.com/react/handbook/composition). Every part renders a default element, and the `render` prop lets you swap it out while keeping the part's behavior, props and ref.

## The render prop [#the-render-prop]

Pass an element to `render` to replace the default element. Dice UI merges its own props, such as ARIA attributes, data attributes, event handlers and the ref, into your element.

```tsx
import { Timeline, TimelineItem } from "@/components/ui/timeline";

return (
  <Timeline render={<ol />}>
    <TimelineItem render={<li />}>Design review</TimelineItem>
  </Timeline>
)
```

Pass a function instead when you need control over where the props go, or want to read the part's state.

```tsx
<TimelineItem
  render={(props) => (
    <li {...props}>
      <a href="/changelog">Release notes</a>
    </li>
  )}
/>
```

## Combining components [#combining-components]

`render` accepts any component that spreads its props onto a DOM element and accepts a `ref`. That includes other Base UI and shadcn/ui parts, so you can layer behaviors onto one element:

```tsx
import { Archive } from "lucide-react";

import { ActionBarItem } from "@/components/ui/action-bar";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";

return (
  <Tooltip>
    <TooltipTrigger render={<ActionBarItem />}>
      <Archive />
    </TooltipTrigger>
    <TooltipContent>Archive</TooltipContent>
  </Tooltip>
)
```

The rendered `button` is both the tooltip trigger and the action bar item.

## Building your own parts [#building-your-own-parts]

To give your own components a `render` prop, use the same tools Dice UI uses: `useRender` and `mergeProps` from `@base-ui/react`, and `useMergedRefs` from `@base-ui/utils`.

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @base-ui/react @base-ui/utils
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @base-ui/react @base-ui/utils
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @base-ui/react @base-ui/utils
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @base-ui/react @base-ui/utils
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```tsx
import { mergeProps } from "@base-ui/react/merge-props";
import { useRender } from "@base-ui/react/use-render";
import { useMergedRefs } from "@base-ui/utils/useMergedRefs";
import * as React from "react";

interface CardProps
  extends React.ComponentProps<"div">,
    useRender.ComponentProps<"div"> {}

function Card({ render, ref, ...props }: CardProps) {
  const localRef = React.useRef<HTMLDivElement>(null);
  const composedRef = useMergedRefs(ref, localRef);

  return useRender({
    defaultTagName: "div",
    render,
    props: mergeProps<"div">(
      { "data-slot": "card", ref: composedRef },
      props,
    ),
  });
}
```

* **`useRender`** renders `defaultTagName`, or the element or function passed to `render`, with the merged props.
* **`mergeProps`** merges props left to right. Event handlers are chained, `className` and `style` are combined, and other props are overridden. It doesn't merge refs.
* **`useMergedRefs`** combines several refs (callback refs or ref objects) into one stable callback ref. Use it when your part needs its own ref as well as the one passed in.

## Migrating from compose-refs [#migrating-from-compose-refs]

Dice UI used to ship a `compose-refs` utility (`@diceui/compose-refs`). It's deprecated, and components no longer install it. Swap the hook for `useMergedRefs`:

```tsx
import { useComposedRefs } from "@/lib/compose-refs"; // [!code --]
import { useMergedRefs } from "@base-ui/utils/useMergedRefs"; // [!code ++]
```

Then delete `lib/compose-refs.ts`. See the [changelog](/docs/changelog/2026-10-composition) for details.


# Direction Provider
URL: /docs/utilities/base/direction-provider



<Callout type="warn">
  **Deprecated.** shadcn/ui now ships a [Direction](https://ui.shadcn.com/docs/components/base/direction) component with the same `DirectionProvider` and `useDirection` API, and Dice UI components use it. Install it instead:

  <CodeBlockTabs defaultValue="npm" groupId="package-manager">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npx shadcn@latest add direction
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm dlx shadcn@latest add direction
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn dlx shadcn@latest add direction
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun x shadcn@latest add direction
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  Then import from `@/components/ui/direction`. This utility will be removed in a future release.
</Callout>

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/direction-provider.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { DirectionProvider } from "@/components/direction-provider"

export default function App() {
  return (
    <DirectionProvider dir="ltr">
      <YourApp />
    </DirectionProvider>
  )
}
```

## API Reference [#api-reference]

### DirectionProvider [#directionprovider]

Manages direction context for the `useDirection` hook.

<AutoTypeTable path="./types/base/utilities.ts" name="DirectionProviderProps" />

### useDirection [#usedirection]

A hook to access the current direction.

```tsx
import { useDirection } from "@/components/direction-provider"

function Component() {
  const dir = useDirection()
  
  return (
    <Button dir={dir}>
      Do a kickflip
    </Button>
  )
}
```

## Notes [#notes]

This is a wrapper around Base UI's DirectionProvider for consistency with existing Dice UI APIs. It may be deprecated in future versions in favor of direct Base UI or shadcn/ui implementations.


# Hitbox
URL: /docs/utilities/base/hitbox



<ComponentTabs name="hitbox-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react class-variance-authority
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/hitbox.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the component and wrap it around any clickable element.

```tsx
import { Hitbox } from "@/components/hitbox";

<Hitbox>
  <Button />
</Hitbox>
```

## Examples [#examples]

### Sizes [#sizes]

Control the size of the extended hitbox area.

<ComponentTabs name="hitbox-sizes-demo" />

### Positions [#positions]

Control which sides of the element the hitbox extends to.

<ComponentTabs name="hitbox-positions-demo" />

### Radii [#radii]

Control the border radius of the hitbox area.

<ComponentTabs name="hitbox-radii-demo" />

### Debug Mode [#debug-mode]

Enable debug mode to visualize the hitbox area during development.

<ComponentTabs name="hitbox-debug-demo" />

## API Reference [#api-reference]

### Hitbox [#hitbox]

The main hitbox component that extends the clickable area of its child element.

<AutoTypeTable path="./types/base/utilities.ts" name="HitboxProps" />

## Sizes [#sizes-1]

The hitbox provides three predefined sizes:

* **`sm`**: 8px extension - Minimal extension for elements that need slight touch area improvement
* **`default`**: 12px extension - Standard extension that helps most elements meet accessibility requirements
* **`lg`**: 16px extension - Generous extension for dense interfaces or critical interactive elements

### Custom Sizes [#custom-sizes]

You can also use custom CSS values for precise control:

```tsx
<Hitbox size="18px">
  <Checkbox />
</Hitbox>
```

## Accessibility [#accessibility]

The hitbox is implemented using a CSS pseudo-element (`::after`) that extends the interactive area without affecting the visual layout or accessibility tree. Screen readers and keyboard navigation work normally.

* **Larger touch targets**: Extends clickable areas to meet minimum touch target size requirements (44px × 44px recommended by WCAG)
* **Better mobile experience**: Reduces precision required for touch interactions
* **Maintains semantics**: Preserves the underlying element's accessibility properties
* **Visual feedback**: Debug mode helps developers ensure adequate touch target sizes

### Touch Target Guidelines [#touch-target-guidelines]

* **Minimum size**: 44px × 44px (iOS) or 48dp × 48dp (Android)
* **Recommended size**: 48px × 48px or larger
* **Spacing**: At least 8px between adjacent touch targets

### Size Recommendations [#size-recommendations]

* **Small buttons (32px)**: Use `default` size (12px) to reach 56px total target
* **Default buttons (36px)**: Use `default` size (12px) to reach 60px total target
* **Large buttons (40px)**: Use `sm` size (8px) to reach 56px total target
* **Icon buttons**: Use `lg` size (16px) for maximum accessibility

### Best Practices [#best-practices]

* Use larger hitboxes for small interactive elements like checkboxes, icons, or close buttons
* Consider different positions (top, bottom, left, right) based on surrounding content
* Test with debug mode enabled to ensure adequate coverage
* Be mindful of overlapping hitboxes that might interfere with each other


# Pending
URL: /docs/utilities/base/pending



<ComponentTabs name="pending-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/pending.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the utility and use it with your interactive elements.

```tsx
import { usePending, Pending } from "@/components/pending";
import { Button } from "@/components/ui/button";

// Using the hook
function SubmitButton() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const { pendingProps, isPending } = usePending({ isPending: isSubmitting });

  return <Button {...pendingProps}>Submit</Button>;
}

// Using the wrapper component
function SubmitButton() {
  const [isSubmitting, setIsSubmitting] = useState(false);

  return (
    <Pending isPending={isSubmitting}>
      <Button>Submit</Button>
    </Pending>
  );
}
```

## Examples [#examples]

### Wrapper Component [#wrapper-component]

Use the `Pending` wrapper component to easily apply pending state to any interactive element.

<ComponentTabs name="pending-wrapper-demo" />

### Form with Pending State [#form-with-pending-state]

Handle form submissions with proper pending state management and user feedback.

<ComponentTabs name="pending-form-demo" />

### Navigation Links [#navigation-links]

Apply pending states to links during async navigation or route transitions.

<ComponentTabs name="pending-link-demo" />

### Toggle Switches [#toggle-switches]

Show pending states on switches that save settings to an API or perform async updates.

<ComponentTabs name="pending-switch-demo" />

## API Reference [#api-reference]

### usePending [#usepending]

A hook that manages pending state for interactive elements. Returns props to spread on your element and the current pending state.

<AutoTypeTable path="./types/base/utilities.ts" name="UsePendingOptions" />

#### Returns [#returns]

<AutoTypeTable path="./types/base/utilities.ts" name="UsePendingReturn" />

### Pending [#pending]

A wrapper component that applies pending state behavior to its child.

<AutoTypeTable path="./types/base/utilities.ts" name="PendingProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-pending]&#x22;,
    value: [&#x22;true&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: [&#x22;true&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

The Pending utility follows best practices for accessible pending states:

* Uses `aria-busy="true"` to indicate loading/pending state to screen readers
* Uses `aria-disabled="true"` to indicate the element is not currently interactive
* Maintains focus ability—users can still Tab to the element
* Prevents all interaction events (click, pointer, keyboard) when pending
* Screen readers announce the changed button content (e.g., "Submitting...")
* Provides `data-pending` attribute for custom styling

## Use Cases [#use-cases]

The Pending utility works with **any interactive element**, not just buttons:

* **Buttons** - Form submissions, actions
* **Links** - Navigation with async route transitions
* **Cards** - Clickable cards that load content
* **Menu Items** - Actions like export, sync, archive
* **Switches/Toggles** - Settings that save to an API
* **Form Fields** - Inputs with async validation
* **Tabs** - Tab switches that load content
* **Select Options** - Dropdowns with async actions
* **Icon Buttons** - Icon-only interactive elements
* **List Items** - Navigation items in sidebars

## Notes [#notes]

* **Choose your API**: Use the `usePending` hook for more control, or the `Pending` wrapper for convenience
* **Focus management**: Elements remain focusable but don't respond to interactions when pending
* **Event prevention**: All pointer and keyboard events are prevented during pending state
* **Styling**: Use the `data-pending` attribute to style elements based on their pending state
* **Accessibility**: Screen readers announce both `aria-busy` (loading state) and `aria-disabled` (not interactive)
* **Hook usage**: When using the hook directly, spread `pendingProps` **last** to ensure event prevention works correctly

## Credits [#credits]

* [React Aria's Button component](https://github.com/adobe/react-spectrum/blob/main/packages/react-aria-components/src/Button.tsx) - For the pending state management patterns (Apache License 2.0).


# Portal
URL: /docs/utilities/base/portal



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/portal.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Portal } from "@/components/portal"

export default function App() {
  return (
    <Portal>
      {/* Content to be rendered in a different part of the DOM */}
      <div>This will be rendered in the document body by default</div>
    </Portal>
  )
}
```

### Custom Container [#custom-container]

Specify a target container for portal rendering:

```tsx
import { Portal } from "@/components/portal"

export default function App() {
  const containerRef = useRef<HTMLDivElement>(null)

  return (
    <>
      <div ref={containerRef} />
      <Portal container={containerRef.current}>
        <div>This will be rendered in the custom container</div>
      </Portal>
    </>
  )
}
```

## API Reference [#api-reference]

### Portal [#portal]

A component that renders its children into a different part of the DOM tree using React's `createPortal`.

#### Props [#props]

<AutoTypeTable path="./types/base/utilities.ts" name="PortalProps" />


# Presence
URL: /docs/utilities/base/presence



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/presence.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Presence } from "@/components/presence"

export default function AnimatedModal({ isOpen }: { isOpen: boolean }) {
  return (
    <Presence present={isOpen}>
      <div className="animate-fade-in">
        Modal content
      </div>
    </Presence>
  )
}
```

### With Render Function [#with-render-function]

Access the present state for exit animations:

```tsx
import { Presence } from "@/components/presence"

export default function FadeModal({ isOpen }: { isOpen: boolean }) {
  return (
    <Presence present={isOpen}>
      {({ present }) => (
        <div 
          className={cn(
            "transition-opacity duration-300",
            present ? "opacity-100" : "opacity-0"
          )}
        >
          Modal content
        </div>
      )}
    </Presence>
  )
}
```

## API Reference [#api-reference]

### Presence [#presence]

Manages the mounting and unmounting of components with animation support.

<AutoTypeTable path="./types/base/utilities.ts" name="PresenceProps" />

## How it Works [#how-it-works]

The `Presence` component ensures that content remains mounted in the DOM during exit animations:

1. When `present` becomes `true`, the element is immediately mounted
2. When `present` becomes `false`, the element stays mounted to allow exit animations
3. The render function receives the current `present` state for conditional styling

This is essential for CSS animations and transitions that need the element to remain in the DOM while animating out.

## Credits [#credits]

Inspired by [Radix UI's Presence primitive](https://github.com/radix-ui/primitives/tree/main/packages/react/presence).


# Skip Nav
URL: /docs/utilities/base/skip-nav



<ComponentTabs name="skip-nav-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/skip-nav.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Render the skip link as the first focusable element on the page, and give your main content the `MAIN_CONTENT_ID` it targets by default.

```tsx
import { MAIN_CONTENT_ID, SkipNav } from "@/components/skip-nav";

<body>
  <SkipNav />
  <header>{/* Navigation */}</header>
  <main id={MAIN_CONTENT_ID}>{/* Page content */}</main>
</body>
```

If your page has a sticky header, give the target a `scroll-margin-top` so it isn't scrolled underneath it.

```tsx
<main id={MAIN_CONTENT_ID} className="scroll-mt-16">
  {/* Page content */}
</main>
```

## Examples [#examples]

### Custom target [#custom-target]

Point `href` at any element on the page and change the label with `children`.

```tsx
<SkipNav href="#search">Skip to search</SkipNav>
```

### Multiple skip links [#multiple-skip-links]

Render more than one when the page has several landmarks worth jumping to.

```tsx
<SkipNav />
<SkipNav href="#footer">Skip to footer</SkipNav>
```

## API Reference [#api-reference]

### SkipNav [#skipnav]

A link that is visually hidden until it receives keyboard focus.

<AutoTypeTable path="./types/base/utilities.ts" name="SkipNavProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-slot]&#x22;,
    value: &#x22;skip-nav&#x22;,
  },
]"
/>

### MAIN\_CONTENT\_ID [#main_content_id]

The `id` that `SkipNav` targets by default, `"main-content"`. Use it on your main content so the link and its target stay in sync.

```tsx
<main id={MAIN_CONTENT_ID}>{/* Page content */}</main>
```

It only applies to the default `href`. When you pass a custom `href`, `SkipNav` ignores `MAIN_CONTENT_ID` and targets the `id` in that `href`, so give that element the matching `id` instead.

```tsx
<SkipNav href="#search">Skip to search</SkipNav>
<input id="search" aria-label="Search" />
```

## Accessibility [#accessibility]

Skip links satisfy [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html). The link stays in the accessibility tree and becomes visible when focused, so sighted keyboard users can see where it goes.

On activation, focus moves to the target element, not just the scroll position. If the target isn't focusable, like `<main>`, it gets `tabindex="-1"` so it can receive focus, and the next <Kbd>Tab</Kbd> continues from there. Its focus outline is hidden while it has focus, and both changes are undone when focus leaves it. The URL hash isn't changed, so the skip doesn't add a history entry.

While focused, the link uses `z-index: 100` to stack above shadcn's `z-50` layers like sticky headers and popovers, so it's never covered ([WCAG 2.4.11 Focus Not Obscured](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)). If your app has its own layers above 100, raise it with `className="focus-visible:z-[…]"`.

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Reveals the skip link when it is the first focusable element.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Moves focus to the target element.&#x22;,
  },
]"
/>


# Visually Hidden Input
URL: /docs/utilities/base/visually-hidden-input



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/visually-hidden-input.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { VisuallyHiddenInput } from "@diceui/visually-hidden-input"

export function CustomForm() {
  const [checked, setChecked] = React.useState(false)
  const controlRef = React.useRef(null)
  
  return (
    <form>
      <button 
        ref={controlRef}
        onClick={() => setChecked(!checked)}
        aria-checked={checked}
        role="checkbox"
      >
        {checked ? "✓" : ""}
      </button>
      <VisuallyHiddenInput
        type="checkbox"
        checked={checked}
        control={controlRef.current}
      />
    </form>
  )
}
```

## API Reference [#api-reference]

### VisuallyHiddenInput [#visuallyhiddeninput]

A hidden input that maintains form functionality while being visually hidden.

<AutoTypeTable path="./types/base/utilities.ts" name="VisuallyHiddenInputProps" />

# Credits [#credits]

* [Radix UI](https://github.com/radix-ui/primitives/blob/main/packages/react/checkbox/src/checkbox.tsx#L165-L212) - Checkbox bubble input


# Visually Hidden
URL: /docs/utilities/base/visually-hidden



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @base-ui/react
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @base-ui/react
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/base/components/visually-hidden.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { VisuallyHidden } from "@diceui/visually-hidden"

export function IconButton() {
  return (
    <button>
      <Icon />
      <VisuallyHidden>Close menu</VisuallyHidden>
    </button>
  )
}
```

## API Reference [#api-reference]

### VisuallyHidden [#visuallyhidden]

Visually hides content while keeping it accessible.

<AutoTypeTable path="./types/base/utilities.ts" name="VisuallyHiddenProps" />


# Client Only
URL: /docs/utilities/radix/client-only



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/client-only
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/hydration-boundary
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/hydration-boundary
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/hydration-boundary
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/hydration-boundary
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/client-only.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { ClientOnly } from "@/components/client-only"

export default function App() {
  return (
    <ClientOnly fallback={<LoadingSpinner />}>
      <ClientComponent />
    </ClientOnly>
  )
}
```

## API Reference [#api-reference]

### ClientOnly [#clientonly]

A component that only renders its children on the client side.

<AutoTypeTable path="./types/radix/utilities.ts" name="ClientOnlyProps" />


# Composition
URL: /docs/utilities/radix/composition



Dice UI's Radix components follow [Radix's composition model](https://www.radix-ui.com/primitives/docs/guides/composition). Every part renders a default element, and the `asChild` prop lets you render your own child instead while keeping the part's behavior, props and ref.

## The asChild prop [#the-aschild-prop]

With `asChild`, the part renders its only child instead of its default element. Dice UI merges its own props, such as ARIA attributes, data attributes, event handlers and the ref, into that child.

```tsx
import { Timeline, TimelineItem } from "@/components/ui/timeline";

return (
  <Timeline asChild>
    <ol>
      <TimelineItem asChild>
        <li>Design review</li>
      </TimelineItem>
    </ol>
  </Timeline>
)
```

## Combining components [#combining-components]

The child can be any component that spreads its props onto a DOM element and accepts a `ref`. That includes other Radix and shadcn/ui parts, so you can layer behaviors onto one element:

```tsx
import { Archive } from "lucide-react";

import { ActionBarItem } from "@/components/ui/action-bar";
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";

return (
  <Tooltip>
    <TooltipTrigger asChild>
      <ActionBarItem>
        <Archive />
      </ActionBarItem>
    </TooltipTrigger>
    <TooltipContent>Archive</TooltipContent>
  </Tooltip>
)
```

The rendered `button` is both the tooltip trigger and the action bar item.

## Building your own parts [#building-your-own-parts]

To give your own components an `asChild` prop, use the same tools Dice UI uses. All of them come from `radix-ui`:

* **`Slot`** renders the child, merging the slot's props into it.
* **`useComposedRefs`*&#x2A; and &#x2A;*`composeRefs`** from `radix-ui/internal` combine several refs.
* **`composeEventHandlers`** from `radix-ui/internal` chains handlers and skips the internal one when yours calls `event.preventDefault()`.

<CodeBlockTabs defaultValue="npm" groupId="package-manager">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install radix-ui
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add radix-ui
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add radix-ui
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add radix-ui
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```tsx
import { Slot as SlotPrimitive } from "radix-ui";
import { composeEventHandlers, useComposedRefs } from "radix-ui/internal";
import * as React from "react";

interface CardProps extends React.ComponentProps<"div"> {
  asChild?: boolean;
}

function Card({ asChild, ref, onKeyDown, ...props }: CardProps) {
  const localRef = React.useRef<HTMLDivElement>(null);
  const composedRef = useComposedRefs(ref, localRef);

  const CardPrimitive = asChild ? SlotPrimitive.Slot : "div";

  return (
    <CardPrimitive
      data-slot="card"
      {...props}
      ref={composedRef}
      onKeyDown={composeEventHandlers(onKeyDown, (event) => {
        if (event.key === "Escape") localRef.current?.blur();
      })}
    />
  );
}
```

`useComposedRefs` returns a stable callback ref, so use it during render. `composeRefs` is the plain function, for when you can't call a hook. Both accept callback refs and ref objects.

## Migrating from compose-refs [#migrating-from-compose-refs]

Dice UI used to ship a `compose-refs` utility (`@diceui/compose-refs`). It's deprecated, and components no longer install it. Import the same helpers from `radix-ui` instead:

```tsx
import { useComposedRefs } from "@/lib/compose-refs"; // [!code --]
import { useComposedRefs } from "radix-ui/internal"; // [!code ++]
```

Then delete `lib/compose-refs.ts`. See the [changelog](/docs/changelog/2026-10-composition) for details.


# Direction Provider
URL: /docs/utilities/radix/direction-provider



<Callout type="warn">
  **Deprecated.** shadcn/ui now ships a [Direction](https://ui.shadcn.com/docs/components/radix/direction) component with the same `DirectionProvider` and `useDirection` API. Install it instead:

  <CodeBlockTabs defaultValue="npm" groupId="package-manager">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npx shadcn@latest add direction
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm dlx shadcn@latest add direction
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn dlx shadcn@latest add direction
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun x shadcn@latest add direction
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  Then import from `@/components/ui/direction`. This utility will be removed in a future release.
</Callout>

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/direction-provider
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/direction-provider
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/direction-provider
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/direction-provider
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/direction-provider
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/direction-provider.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

For data grid and other tablecn components, use the shadcn-style `direction` component at `@/components/ui/direction` instead — it ships automatically with those installs. This utility is for Dice UI components that depend on `@diceui/direction-provider`.

```tsx
import { DirectionProvider } from "@diceui/direction-provider"

export default function App() {
  return (
    <DirectionProvider dir="ltr">
      <YourApp />
    </DirectionProvider>
  )
}
```

## API Reference [#api-reference]

### DirectionProvider [#directionprovider]

Manages direction context for the `useDirection` hook.

<AutoTypeTable path="./types/radix/utilities.ts" name="DirectionProviderProps" />

### useDirection [#usedirection]

A hook to access the current direction.

```tsx
import { useDirection } from "@/components/direction-provider"

function Component() {
  const dir = useDirection()
  
  return (
    <Button dir={dir}>
      Do a kickflip
    </Button>
  )
}
```


# Hitbox
URL: /docs/utilities/radix/hitbox



<ComponentTabs name="hitbox-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/hitbox
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="hitbox" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the component and wrap it around any interactive element.

```tsx
import { Hitbox } from "@/components/hitbox";

<Hitbox>
  <Button />
</Hitbox>
```

## Examples [#examples]

### Sizes [#sizes]

Control the size of the extended hitbox area.

<ComponentTabs name="hitbox-sizes-demo" />

### Positions [#positions]

Control which sides of the element the hitbox extends to.

<ComponentTabs name="hitbox-positions-demo" />

### Radii [#radii]

Control the border radius of the hitbox area.

<ComponentTabs name="hitbox-radii-demo" />

### Debug Mode [#debug-mode]

Enable debug mode to visualize the hitbox area during development.

<ComponentTabs name="hitbox-debug-demo" />

## API Reference [#api-reference]

### Hitbox [#hitbox]

The main hitbox component that extends the clickable area of its child element.

<AutoTypeTable path="./types/radix/utilities.ts" name="HitboxProps" />

## Sizes [#sizes-1]

The hitbox provides three predefined sizes:

* **`sm`**: 8px extension - Minimal extension for elements that need slight touch area improvement
* **`default`**: 12px extension - Standard extension that helps most elements meet accessibility requirements
* **`lg`**: 16px extension - Generous extension for dense interfaces or critical interactive elements

### Custom Sizes [#custom-sizes]

You can also use custom CSS values for precise control:

```tsx
<Hitbox size="18px">
  <Checkbox />
</Hitbox>
```

## Accessibility [#accessibility]

The Hitbox component improves accessibility by:

* **Larger touch targets**: Extends clickable areas to meet minimum touch target size requirements (44px × 44px recommended by WCAG)
* **Better mobile experience**: Reduces precision required for touch interactions
* **Maintains semantics**: Uses Radix UI's Slot component to preserve the underlying element's accessibility properties
* **Visual feedback**: Debug mode helps developers ensure adequate touch target sizes

### Touch Target Guidelines [#touch-target-guidelines]

* **Minimum size**: 44px × 44px (iOS) or 48dp × 48dp (Android)
* **Recommended size**: 48px × 48px or larger
* **Spacing**: At least 8px between adjacent touch targets

### Size Recommendations [#size-recommendations]

* **Small buttons (32px)**: Use `default` size (12px) to reach 56px total target
* **Default buttons (36px)**: Use `default` size (12px) to reach 60px total target
* **Large buttons (40px)**: Use `sm` size (8px) to reach 56px total target
* **Icon buttons**: Use `lg` size (16px) for maximum accessibility

### Best Practices [#best-practices]

* Use larger hitboxes for small interactive elements like checkboxes, icons, or close buttons
* Consider different positions (top, bottom, left, right) based on surrounding content
* Test with debug mode enabled to ensure adequate coverage
* Be mindful of overlapping hitboxes that might interfere with each other


# Pending
URL: /docs/utilities/radix/pending



<ComponentTabs name="pending-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/pending
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="pending" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Import the utility and use it with your interactive elements.

```tsx
import { usePending, Pending } from "@/components/pending";
import { Button } from "@/components/ui/button";

// Using the hook
function SubmitButton() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const { pendingProps, isPending } = usePending({ isPending: isSubmitting });

  return <Button {...pendingProps}>Submit</Button>;
}

// Using the wrapper component
function SubmitButton() {
  const [isSubmitting, setIsSubmitting] = useState(false);

  return (
    <Pending isPending={isSubmitting}>
      <Button>Submit</Button>
    </Pending>
  );
}
```

## Examples [#examples]

### Wrapper Component [#wrapper-component]

Use the `Pending` wrapper component to easily apply pending state to any interactive element using Radix Slot.

<ComponentTabs name="pending-wrapper-demo" />

### Form with Pending State [#form-with-pending-state]

Handle form submissions with proper pending state management and user feedback.

<ComponentTabs name="pending-form-demo" />

### Navigation Links [#navigation-links]

Apply pending states to links during async navigation or route transitions.

<ComponentTabs name="pending-link-demo" />

### Toggle Switches [#toggle-switches]

Show pending states on switches that save settings to an API or perform async updates.

<ComponentTabs name="pending-switch-demo" />

## API Reference [#api-reference]

### usePending [#usepending]

A hook that manages pending state for interactive elements. Returns props to spread on your element and the current pending state.

<AutoTypeTable path="./types/radix/utilities.ts" name="UsePendingOptions" />

#### Returns [#returns]

<AutoTypeTable path="./types/radix/utilities.ts" name="UsePendingReturn" />

### Pending [#pending]

A wrapper component that applies pending state behavior to its child using Radix Slot.

<AutoTypeTable path="./types/radix/utilities.ts" name="PendingProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-pending]&#x22;,
    value: [&#x22;true&#x22;],
  },
  {
    title: &#x22;[data-disabled]&#x22;,
    value: [&#x22;true&#x22;],
  },
]"
/>

## Accessibility [#accessibility]

The Pending utility follows best practices for accessible pending states:

* Uses `aria-busy="true"` to indicate loading/pending state to screen readers
* Uses `aria-disabled="true"` to indicate the element is not currently interactive
* Maintains focus ability—users can still Tab to the element
* Prevents all interaction events (click, pointer, keyboard) when pending
* Screen readers announce the changed button content (e.g., "Submitting...")
* Provides `data-pending` attribute for custom styling

## Use Cases [#use-cases]

The Pending utility works with **any interactive element**, not just buttons:

* **Buttons** - Form submissions, actions
* **Links** - Navigation with async route transitions
* **Cards** - Clickable cards that load content
* **Menu Items** - Actions like export, sync, archive
* **Switches/Toggles** - Settings that save to an API
* **Form Fields** - Inputs with async validation
* **Tabs** - Tab switches that load content
* **Select Options** - Dropdowns with async actions
* **Icon Buttons** - Icon-only interactive elements
* **List Items** - Navigation items in sidebars

## Notes [#notes]

* **Choose your API**: Use the `usePending` hook for more control, or the `Pending` wrapper for convenience
* **Focus management**: Elements remain focusable but don't respond to interactions when pending
* **Event prevention**: All pointer and keyboard events are prevented during pending state
* **Styling**: Use the `data-pending` attribute to style elements based on their pending state
* **Accessibility**: Screen readers announce both `aria-busy` (loading state) and `aria-disabled` (not interactive)
* **Hook usage**: When using the hook directly, spread `pendingProps` **last** to ensure event prevention works correctly

## Credits [#credits]

* [React Aria's Button component](https://github.com/adobe/react-spectrum/blob/main/packages/react-aria-components/src/Button.tsx) - For the pending state management patterns (Apache License 2.0).


# Portal
URL: /docs/utilities/radix/portal



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/portal
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/portal.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Portal } from "@/components/portal"

export default function App() {
  return (
    <Portal>
      {/* Content to be rendered in a different part of the DOM */}
      <div>This will be rendered in the document body by default</div>
    </Portal>
  )
}
```

### Custom Container [#custom-container]

Specify a target container for portal rendering:

```tsx
import { Portal } from "@/components/portal"

export default function App() {
  const containerRef = useRef<HTMLDivElement>(null)

  return (
    <>
      <div ref={containerRef} />
      <Portal container={containerRef.current}>
        <div>This will be rendered in the custom container</div>
      </Portal>
    </>
  )
}
```

## API Reference [#api-reference]

### Portal [#portal]

A component that renders its children into a different part of the DOM tree using React's `createPortal`.

#### Props [#props]

<AutoTypeTable path="./types/radix/utilities.ts" name="PortalProps" />


# Presence
URL: /docs/utilities/radix/presence



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/presence
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/presence.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { Presence } from "@/components/presence"

export default function App() {
  const [open, setOpen] = React.useState(false)

  return (
    <Presence present={open}>
      <div
        data-state={open ? "open" : "closed"}
        className="data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=open]:animate-in"
      >
        This content will animate in and out
      </div>
    </Presence>
  )
}
```

### Render Function Pattern [#render-function-pattern]

Access presence state through a render function:

```tsx
import { Presence } from "@/components/presence"

export default function App() {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <Presence present={isOpen}>
      {({ present }) => (
        <div className={present ? "animate-in fade-in-0" : "animate-out fade-out-0"}>
          This content will animate based on presence state
        </div>
      )}
    </Presence>
  )
}
```

### Force Mounting [#force-mounting]

Use `forceMount` to keep elements mounted regardless of presence state. Useful for accessibility requirements and focus management:

```tsx
import { Presence } from "@/components/presence"

export default function App() {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <Presence present={isOpen} forceMount>
      <div 
        className={cn(
          "transition-opacity duration-200",
          isOpen ? "opacity-100" : "opacity-0"
        )}
      >
        This content will always be mounted but will fade in/out
      </div>
    </Presence>
  )
}
```

## API Reference [#api-reference]

### Presence [#presence]

A component that manages the presence state of elements with support for animations. It handles mounting, unmounting, and animation states automatically.

<AutoTypeTable path="./types/radix/utilities.ts" name="PresenceProps" />


# Skip Nav
URL: /docs/utilities/radix/skip-nav



<ComponentTabs name="skip-nav-demo" />

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/skip-nav
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add radix-ui
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add radix-ui
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/skip-nav.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Layout [#layout]

Render the skip link as the first focusable element on the page, and give your main content the `MAIN_CONTENT_ID` it targets by default.

```tsx
import { MAIN_CONTENT_ID, SkipNav } from "@/components/skip-nav";

<body>
  <SkipNav />
  <header>{/* Navigation */}</header>
  <main id={MAIN_CONTENT_ID}>{/* Page content */}</main>
</body>
```

If your page has a sticky header, give the target a `scroll-margin-top` so it isn't scrolled underneath it.

```tsx
<main id={MAIN_CONTENT_ID} className="scroll-mt-16">
  {/* Page content */}
</main>
```

## Examples [#examples]

### Custom target [#custom-target]

Point `href` at any element on the page and change the label with `children`.

```tsx
<SkipNav href="#search">Skip to search</SkipNav>
```

### Multiple skip links [#multiple-skip-links]

Render more than one when the page has several landmarks worth jumping to.

```tsx
<SkipNav />
<SkipNav href="#footer">Skip to footer</SkipNav>
```

## API Reference [#api-reference]

### SkipNav [#skipnav]

A link that is visually hidden until it receives keyboard focus.

<AutoTypeTable path="./types/radix/utilities.ts" name="SkipNavProps" />

<DataAttributesTable
  data="[
  {
    title: &#x22;[data-slot]&#x22;,
    value: &#x22;skip-nav&#x22;,
  },
]"
/>

### MAIN\_CONTENT\_ID [#main_content_id]

The `id` that `SkipNav` targets by default, `"main-content"`. Use it on your main content so the link and its target stay in sync.

```tsx
<main id={MAIN_CONTENT_ID}>{/* Page content */}</main>
```

It only applies to the default `href`. When you pass a custom `href`, `SkipNav` ignores `MAIN_CONTENT_ID` and targets the `id` in that `href`, so give that element the matching `id` instead.

```tsx
<SkipNav href="#search">Skip to search</SkipNav>
<input id="search" aria-label="Search" />
```

## Accessibility [#accessibility]

Skip links satisfy [WCAG 2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html). The link stays in the accessibility tree and becomes visible when focused, so sighted keyboard users can see where it goes.

On activation, focus moves to the target element, not just the scroll position. If the target isn't focusable, like `<main>`, it gets `tabindex="-1"` so it can receive focus, and the next <Kbd>Tab</Kbd> continues from there. Its focus outline is hidden while it has focus, and both changes are undone when focus leaves it. The URL hash isn't changed, so the skip doesn't add a history entry.

While focused, the link uses `z-index: 100` to stack above shadcn's `z-50` layers like sticky headers and popovers, so it's never covered ([WCAG 2.4.11 Focus Not Obscured](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html)). If your app has its own layers above 100, raise it with `className="focus-visible:z-[…]"`.

### Keyboard Interactions [#keyboard-interactions]

<KeyboardShortcutsTable
  data="[
  {
    keys: [&#x22;Tab&#x22;],
    description: &#x22;Reveals the skip link when it is the first focusable element.&#x22;,
  },
  {
    keys: [&#x22;Enter&#x22;],
    description: &#x22;Moves focus to the target element.&#x22;,
  },
]"
/>


# Visually Hidden Input
URL: /docs/utilities/radix/visually-hidden-input



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/visually-hidden-input
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/visually-hidden-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/visually-hidden-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/visually-hidden-input
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/visually-hidden-input
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/visually-hidden-input.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { VisuallyHiddenInput } from "@diceui/visually-hidden-input"

export function CustomForm() {
  const [checked, setChecked] = React.useState(false)
  const controlRef = React.useRef(null)
  
  return (
    <form>
      <button 
        ref={controlRef}
        onClick={() => setChecked(!checked)}
        aria-checked={checked}
        role="checkbox"
      >
        {checked ? "✓" : ""}
      </button>
      <VisuallyHiddenInput
        type="checkbox"
        checked={checked}
        control={controlRef.current}
      />
    </form>
  )
}
```

## API Reference [#api-reference]

### VisuallyHiddenInput [#visuallyhiddeninput]

A hidden input that maintains form functionality while being visually hidden.

<AutoTypeTable path="./types/radix/utilities.ts" name="VisuallyHiddenInputProps" />

# Credits [#credits]

* [Radix UI](https://github.com/radix-ui/primitives/blob/main/packages/react/checkbox/src/checkbox.tsx#L165-L212) - Checkbox bubble input


# Visually Hidden
URL: /docs/utilities/radix/visually-hidden



## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTrigger value="cli">
      Command
    </TabsTrigger>

    <TabsTrigger value="manual">
      Manual
    </TabsTrigger>
  </TabsList>

  <TabsContent value="cli">
    <CodeBlockTabs defaultValue="npm" groupId="package-manager">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="npm">
        ```bash
        npx shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm dlx shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn dlx shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun x shadcn@latest add @diceui/visually-hidden
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </TabsContent>

  <TabsContent value="manual">
    <Steps className="pt-2">
      <Step>
        Install the following dependencies:
      </Step>

      <CodeBlockTabs defaultValue="npm" groupId="package-manager">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="npm">
            npm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="pnpm">
            pnpm
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="yarn">
            yarn
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="bun">
            bun
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="npm">
          ```bash
          npm install @diceui/visually-hidden
          ```
        </CodeBlockTab>

        <CodeBlockTab value="pnpm">
          ```bash
          pnpm add @diceui/visually-hidden
          ```
        </CodeBlockTab>

        <CodeBlockTab value="yarn">
          ```bash
          yarn add @diceui/visually-hidden
          ```
        </CodeBlockTab>

        <CodeBlockTab value="bun">
          ```bash
          bun add @diceui/visually-hidden
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource src="./registry/bases/radix/components/visually-hidden.tsx" />
    </Steps>
  </TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx
import { VisuallyHidden } from "@diceui/visually-hidden"

export function IconButton() {
  return (
    <button>
      <Icon />
      <VisuallyHidden>Close menu</VisuallyHidden>
    </button>
  )
}
```

## API Reference [#api-reference]

### VisuallyHidden [#visuallyhidden]

Visually hides content while keeping it accessible.

<AutoTypeTable path="./types/radix/utilities.ts" name="VisuallyHiddenProps" />