# HextaUI

> Ready-to-use foundation components/blocks built on top of shadcn/ui. Accessible React components on Base UI and Tailwind CSS v4 that you copy into your project and own.

HextaUI keeps the shadcn/ui API and adds the details that make an interface feel finished: interruptible motion, reduced-motion fallbacks, keyboard support, right-to-left layouts and touch-sized targets. Every component is tested against its edge cases before it ships.

- Install a component with the shadcn CLI: `npx shadcn@latest add https://hextaui.com/r/<name>.json`. It adds the source, the HextaUI theme tokens and any HextaUI components it depends on. `https://hextaui.com/r/all.json` installs every component.
- The code is then owned by the project, like shadcn/ui. There is no HextaUI npm package. HextaUI is MIT licensed and free for personal and commercial use.
- Behavior and accessibility come from Base UI (`@base-ui/react`). Compose with the `render` prop, not `asChild`.
- Styling uses Tailwind CSS v4 with theme tokens. Merge classes with `cn` from the `cn` package.
- Icons come from `@tabler/icons-react`.
- Import components from `@/components/ui/<name>`, hooks from `@/hooks/<name>` and utilities from `@/lib/<name>`.
- Each component page lists its dependencies, the full source to copy, usage, examples, keyboard support and an API reference.
- The shadcn registry index is https://hextaui.com/r/registry.json. Register it as a namespace in components.json with `"registries": { "@hextaui": "https://hextaui.com/r/{name}.json" }` to run `npx shadcn@latest add @hextaui/<name>` or browse it through the shadcn MCP server.
- Without the CLI, add the theme tokens from https://hextaui.com/docs/installation#theme before copying component files.
- Append `.md` to any docs URL for its Markdown, for example https://hextaui.com/docs/button.md.

## Docs

- [Introduction](https://hextaui.com/docs.md): What HextaUI is, what it is built on and the principles behind it.
- [Installation](https://hextaui.com/docs/installation.md): Add HextaUI with the shadcn CLI or by hand, register the @hextaui namespace, the theme tokens, and setup for AI assistants.
- [MCP server](https://hextaui.com/docs/mcp.md): Connect Claude Code, Cursor, VS Code and other AI assistants to HextaUI, so they search the docs, read each API and install components for you.

## Components

- [Accordion](https://hextaui.com/docs/accordion.md): Stacked headings that each reveal a panel, with height motion you can reverse mid-way and panels that stay searchable while closed.
- [Alert](https://hextaui.com/docs/alert.md): Inline messages for status and feedback, with a neutral surface, a colored icon and a dismiss that collapses smoothly.
- [Alert dialog](https://hextaui.com/docs/alert-dialog.md): A confirmation dialog for destructive or important actions that waits for async work, and becomes a bottom sheet on phones.
- [Aspect ratio](https://hextaui.com/docs/aspect-ratio.md): A box that holds its shape before media loads, shimmers while loading, fades the media in and falls back when it fails.
- [Attachment](https://hextaui.com/docs/attachment.md): File and image cards for uploads, with progress, states, actions, a full-card trigger and names that keep their extension.
- [Avatar](https://hextaui.com/docs/avatar.md): User photos with an initials fallback, status badges and stacked groups that collapse into a count.
- [Badge](https://hextaui.com/docs/badge.md): Status labels with colored dots, removable tags that slide closed and counts that roll to their new value.
- [Breadcrumb](https://hextaui.com/docs/breadcrumb.md): A trail of links to the current page that wraps safely, mirrors in right-to-left layouts and expands collapsed segments in place.
- [Bubble](https://hextaui.com/docs/bubble.md): Chat message bubbles with variants, grouped corners, reactions and room for interactive content.
- [Button](https://hextaui.com/docs/button.md): Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- [Button group](https://hextaui.com/docs/button-group.md): Buttons joined into one control, with shared seams, separators, text addons, nesting and vertical stacks.
- [Calendar](https://hextaui.com/docs/calendar.md): A date grid for single, range and multiple selection, with sliding months, range previews and touch-sized days.
- [Card](https://hextaui.com/docs/card.md): A surface for grouping content, with three variants, edge-to-edge media, concentric radii and whole-card links.
- [Carousel](https://hextaui.com/docs/carousel.md): Native scroll-snap slides with momentum on touch, mouse dragging, arrow keys, dots, thumbnails and an autoplay that pauses when it should.
- [Chart](https://hextaui.com/docs/chart.md): Recharts charts with themed colors, a tooltip and legend that read labels from one config, and keyboard navigation with a visible focus ring.
- [Checkbox](https://hextaui.com/docs/checkbox.md): A checkbox whose check draws in, with indeterminate parents, groups and labels that share its hover.
- [Collapsible](https://hextaui.com/docs/collapsible.md): A panel that shows and hides with height motion you can reverse mid-way, without jumping the layout.
- [Combobox](https://hextaui.com/docs/combobox.md): A filterable select with chips, groups and async results, in a popup that resizes as you type.
- [Command](https://hextaui.com/docs/command.md): A searchable list of actions, inline or as a ⌘K palette, with pages, shortcuts and highlighted matches.
- [Context menu](https://hextaui.com/docs/context-menu.md): A menu of actions on right click or long press, with submenus, checkbox and radio items, and hold feedback on touch.
- [Data table](https://hextaui.com/docs/data-table.md): A table for real data, with sorting, search, row selection, pinned columns, a sticky header and pagination.
- [Date picker](https://hextaui.com/docs/date-picker.md): A button that opens a calendar in a popover, or a bottom sheet on phones, for single dates and ranges.
- [Dialog](https://hextaui.com/docs/dialog.md): A window over the page for forms and focused tasks, with a pinned header and footer, nesting, and a swipeable bottom sheet on phones.
- [Drawer](https://hextaui.com/docs/drawer.md): A panel that slides in from any edge and follows your finger, with snap points, a working handle and nested drawers that stack.
- [Dropdown menu](https://hextaui.com/docs/dropdown-menu.md): A menu of actions and options behind a button, with groups, submenus, checkbox and radio items, and shortcuts.
- [Empty](https://hextaui.com/docs/empty.md): A placeholder for screens with nothing to show yet, with an icon, a message and the next action.
- [Field](https://hextaui.com/docs/field.md): Labels, descriptions and errors wired to their control, with validation states and layouts for forms.
- [Hover card](https://hextaui.com/docs/hover-card.md): A preview card that opens when a link is hovered or focused, for content sighted users can glance at.
- [Input](https://hextaui.com/docs/input.md): A text input with three sizes, invalid and read-only states, native validation styling and a 16px touch font so phones never zoom in.
- [Input group](https://hextaui.com/docs/input-group.md): An input with icons, text, buttons or a keyboard hint attached, sharing one border and focus ring.
- [Input OTP](https://hextaui.com/docs/input-otp.md): One-time code slots that take typing, paste and SMS autofill, with an opt-in animation that cascades codes in and a status for verifying.
- [Item](https://hextaui.com/docs/item.md): A row of media, text and actions for lists, settings and pickers, with a grouped surface and a hover highlight that glides between rows.
- [Kbd](https://hextaui.com/docs/kbd.md): Key caps for shortcuts that show the right symbols on every platform, read them out properly and press down with the real keys.
- [Label](https://hextaui.com/docs/label.md): A label that follows its control, dimming when it's disabled and marking it required or optional on its own.
- [Marker](https://hextaui.com/docs/marker.md): Quiet notes between content, like date dividers and system events, with sticky dates and times that read as Today or Yesterday.
- [Menubar](https://hextaui.com/docs/menubar.md): A desktop-style bar of menus with one highlight that slides between open menus and instant switching as you sweep across.
- [Message](https://hextaui.com/docs/message.md): A chat message row with an avatar, name, bubbles and status, where new messages rise in from the sender's side.
- [Message scroller](https://hextaui.com/docs/message-scroller.md): A chat scroll area that follows new messages, keeps your place while you read back, and counts what you missed on the jump button.
- [Native select](https://hextaui.com/docs/native-select.md): The browser's own select, styled to match Input, with a quiet placeholder, Field support and the OS picker on every device.
- [Navigation menu](https://hextaui.com/docs/navigation-menu.md): Site navigation with dropdowns, or one full-width panel that stays open while its content slides between menus.
- [Number flow](https://hextaui.com/docs/number-flow.md): Animated numbers where only the changed digits spin, with any Intl format and locale.
- [Pagination](https://hextaui.com/docs/pagination.md): Page navigation that keeps every button in place, glides to the current page and jumps to any page from the ellipsis.
- [Popover](https://hextaui.com/docs/popover.md): A floating panel anchored to a trigger that resizes smoothly with its content and follows the trigger’s direction.
- [Progress](https://hextaui.com/docs/progress.md): A bar or ring that shows how far a task has come, eases between updates and slides while the total is unknown.
- [Questionnaire](https://hextaui.com/docs/questionnaire.md): A step-by-step form that moves between questions with a sense of direction, shows real progress and answers from the keyboard.
- [Radio group](https://hextaui.com/docs/radio-group.md): Pick one option from a set, with a dot that hands off between choices and cards whose selection ring slides to the new pick.
- [Resizable](https://hextaui.com/docs/resizable.md): Panels you can drag apart, with a quiet divider that wakes up on hover, sizes that glide on reset or collapse, and layouts that persist.
- [Scroll area](https://hextaui.com/docs/scroll-area.md): Native scrolling with a minimal scrollbar, edges that fade only where there’s more to see, and an optional peek that cuts the last item in half.
- [Select](https://hextaui.com/docs/select.md): Pick one or more options from a list that opens on the current value, with typeahead, groups and form support.
- [Separator](https://hextaui.com/docs/separator.md): A hairline that divides content horizontally or vertically, with an optional label and a decorative mode for purely visual lines.
- [Sheet](https://hextaui.com/docs/sheet.md): A panel that slides in from any edge, with swipe-to-dismiss, scroll lock and stacked nesting.
- [Sidebar](https://hextaui.com/docs/sidebar.md): An app sidebar that collapses to icons or off canvas, stays pinned under your header, and becomes a swipeable sheet on phones.
- [Skeleton](https://hextaui.com/docs/skeleton.md): Placeholders that wait 150ms before showing, take the exact size of the content they wrap, and fade it in without moving anything.
- [Slider](https://hextaui.com/docs/slider.md): Pick a value or a range by dragging, tapping the track or using the keys, with jumps that glide and an optional value bubble.
- [Spinner](https://hextaui.com/docs/spinner.md): A loading indicator with Apple-style ticks or a breathing ring that can wait before showing and stay long enough not to flicker.
- [Switch](https://hextaui.com/docs/switch.md): An on/off toggle you can tap, press or drag, with a thumb that stretches under your finger and an optional pending state for saves.
- [Table](https://hextaui.com/docs/table.md): A responsive table with a surface style, wrapping or compact cells, sticky headers, pinned columns and scroll hints.
- [Tabs](https://hextaui.com/docs/tabs.md): Switch between views with an indicator that slides to the active tab, as a segmented control or an underline, and lists that scroll when they overflow.
- [Textarea](https://hextaui.com/docs/textarea.md): Multi-line text that grows smoothly with what you write between a minimum and maximum number of rows, with counters, validation and a submit shortcut.
- [Toast](https://hextaui.com/docs/toast.md): Brief messages that stack neatly, expand on hover, swipe away, and turn a loading state into success or error in place.
- [Toggle](https://hextaui.com/docs/toggle.md): A button that stays on or off, with a fill that settles in when pressed, a clear hover-to-on step and icons that can fill with the state.
- [Toggle group](https://hextaui.com/docs/toggle-group.md): A row of toggles for one choice or many, with a fill that slides to the picked item, joined or spaced items and arrow-key focus.
- [Tooltip](https://hextaui.com/docs/tooltip.md): A short hint on hover or keyboard focus that opens after a brief rest, switches instantly between neighbours and shows shortcuts.
- [Tree](https://hextaui.com/docs/tree.md): Nested, expandable rows for files and hierarchies, with indent guides, connector lines, cascading checkboxes, typeahead and full keyboard support.
- [Video player](https://hextaui.com/docs/video-player.md): A video player with a scrubbable seek bar, auto-hiding controls, keyboard shortcuts, speed, picture in picture and full screen.

## Hooks

- [useAutosize](https://hextaui.com/docs/use-autosize.md): Grows a textarea with what you write between its minimum and maximum height, animating each change without ever touching the text.
- [useButtonFeedback](https://hextaui.com/docs/use-button-feedback.md): Runs an async action through loading, success and error, skipping the spinner for fast requests and holding an error while you read it.
- [useComposedRef](https://hextaui.com/docs/use-composed-ref.md): Keeps a ref to your own element while still forwarding it to whatever ref the parent passed in.
- [useDelayedLoading](https://hextaui.com/docs/use-delayed-loading.md): Shows a loading state only when work is actually slow, then keeps it up long enough that it never flickers.
- [useHeldKeys](https://hextaui.com/docs/use-held-keys.md): The keys someone is holding down right now, shared by every subscriber through a single set of window listeners.
- [useInvalidShake](https://hextaui.com/docs/use-invalid-shake.md): Shakes a form control when a submit attempt finds it invalid, and never while someone is still typing.
- [useMergedRef](https://hextaui.com/docs/use-merged-ref.md): Combines any number of callback and object refs into one, with React 19 ref cleanup for each of them.
- [usePagination](https://hextaui.com/docs/use-pagination.md): Turns a page and a page count into the list of pages and ellipses to render, keeping its length steady as the page moves.
- [useToday](https://hextaui.com/docs/use-today.md): Today's date that rolls over at midnight and when the tab comes back, without a hydration mismatch.

## Utilities

- [Hairline](https://hextaui.com/docs/hairline.md): Borders and rings exactly one device pixel wide on every screen, through one variable the whole theme reads.
- [Hotkey](https://hextaui.com/docs/hotkey.md): Parse, label, announce and match keyboard shortcuts, with ⌘ on Apple platforms and Ctrl everywhere else.
- [Motion](https://hextaui.com/docs/motion.md): The easing curves, durations and reduced-motion check every component animates with, plus hooks for size morphs and sliding highlights.
- [Scroll fade](https://hextaui.com/docs/scroll-fade.md): Edges of a scroll area that fade only when there's more to see, driven by the scroll position in CSS alone.
- [Shimmer](https://hextaui.com/docs/shimmer.md): A band of light that sweeps across text for in-progress states, tinted from the text color and still under reduced motion.

## Optional

- [Full documentation](https://hextaui.com/llms-full.txt): Every docs page in one file, with usage, installation, keyboard support and API reference. Component source and example code live in each component's Markdown page.

---

# Introduction

> Ready-to-use foundation components/blocks built on top of shadcn/ui.

Docs: https://hextaui.com/docs
Markdown: https://hextaui.com/docs.md

## What is HextaUI

HextaUI is a collection of 65 components, 9 hooks and 5 utilities for React. You add them with the shadcn CLI, the source lands in your project, and from then on it's your code to read and change.

Every component keeps the shadcn/ui API you already know. What's different is the work you would otherwise do yourself: the states, the edge cases and the small details that make an interface feel finished.

## Quick start

In a project set up with shadcn/ui, add a component:

```bash
npx shadcn@latest add https://hextaui.com/r/button.json
```

Then import it from `@/components/ui`.

```tsx
import { Button } from "@/components/ui/button"

export function SaveButton() {
  return (
    <Button feedback onClick={() => saveSettings()}>
      Save changes
    </Button>
  )
}
```

Requirements, adding everything at once and the `@hextaui` namespace are covered in [Installation](https://hextaui.com/docs/installation).

## What you get

These hold for every component, so you don't have to check each one.

### Motion

Animations use the theme's easing curves and can be interrupted and reversed mid-way. When reduced motion is on, movement turns into a simple fade.

### Keyboard and screen readers

Everything works with the keyboard alone, and focus goes where you expect when popups open and close. Changes are announced too: toasts, loading and saved states, selections and slide changes.

### Touch and small screens

Tap targets grow on touch screens, text inputs stay at 16px so iOS doesn't zoom in, and popups stay on screen down to 320px wide. Layouts mirror for right-to-left languages.

### High contrast

Focus rings, control edges and selected states stay visible in Windows high contrast mode, and the default theme meets WCAG AA contrast in light and dark.

## Built on

- shadcn/ui with the `base-vega` style
- Base UI primitives for behavior and accessibility
- Tailwind CSS v4, with theme tokens for color, radius and easing
- Tabler icons

## AI assistants

Every page has a Markdown version, and `/llms.txt` lists them all. Assistants that support MCP can connect to the [HextaUI MCP server](https://hextaui.com/docs/mcp) to search the docs, read component APIs and get install commands.

## License

HextaUI is open source under the [MIT license](https://github.com/preetsuthar17/hextaui/blob/main/LICENSE), free for personal and commercial projects.

---

# Installation

> Add HextaUI to a React project with the shadcn CLI, or copy the files in by hand.

Docs: https://hextaui.com/docs/installation
Markdown: https://hextaui.com/docs/installation.md

## Requirements

A React 19 project with Tailwind CSS v4 and a `components.json`. If you don't have one yet, set it up with the shadcn CLI.

```bash
npx shadcn@latest init
```

## Add components

Pass a component's registry URL to the CLI. It copies the source into your project, installs its dependencies, adds the theme tokens and pulls in any HextaUI components it builds on.

```bash
npx shadcn@latest add https://hextaui.com/r/button.json
```

Add every component at once with:

```bash
npx shadcn@latest add https://hextaui.com/r/all.json
```

The files are yours from then on. Import them from `@/components/ui` and edit them like any other code.

## Namespace

Register HextaUI in `components.json` to add components by name.

```json title="components.json"
{
  "registries": {
    "@hextaui": "https://hextaui.com/r/{name}.json"
  }
}
```

```bash
npx shadcn@latest add @hextaui/button
```

## Theme

Components use a few tokens on top of shadcn/ui: status colors, easing curves, a hairline border width and the keyframes they animate with. The CLI adds them for you. When copying files by hand, add this to your global CSS once.

```css title="app/globals.css"
@import "tw-animate-css";
@import "shadcn/tailwind.css";

@theme inline {
  --color-destructive-foreground: var(--destructive-foreground);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
  --color-focus-ring: color-mix(in oklab, var(--foreground) 40%, transparent);
  --color-canvas: Canvas;
  --color-canvas-text: CanvasText;
  --color-highlight: Highlight;
  --color-highlight-text: HighlightText;
  --color-gray-text: GrayText;
  --font-weight-book: 520;
  --ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
  --ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
  --ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
  --ease-spring: linear(0, 0.015 2%, 0.0532 4%, 0.1065 6%, 0.1686 8%, 0.2351 10%, 0.3363 13%, 0.4332 16%, 0.5495 20%, 0.648 24%, 0.7287 28%, 0.807 33%, 0.8646 38%, 0.9128 44%, 0.9447 50%, 0.968 57%, 0.9834 65%, 0.9924 74%, 0.9975 85%, 1);
  --default-border-width: var(--hairline);
  --text-xs: 0.6875rem;
  --text-sm: 0.8125rem;
  --text-base: 0.9375rem;
  --text-lg: 1.0625rem;
  --text-xl: 1.1875rem;
  --text-2xl: 1.4375rem;
  --text-3xl: 1.8125rem;
  --text-4xl: 2.1875rem;
  --text-5xl: 2.9375rem;
  --text-6xl: 3.6875rem;
  --text-7xl: 4.4375rem;
  --text-8xl: 5.9375rem;
  --text-9xl: 7.9375rem;
  --text-touch: max(16px, 1rem);
  --animate-shimmer: shimmer 1.6s ease-in-out infinite;
  --animate-skeleton-pulse: skeleton-pulse 2s ease-in-out infinite;
  --animate-button-state-in: button-state-in 220ms cubic-bezier(0.2, 0, 0, 1) both;
  --animate-button-state-out: button-state-out 220ms cubic-bezier(0.2, 0, 0, 1) both;
  --animate-button-draw-circle: button-draw 240ms cubic-bezier(0.2, 0, 0, 1) both;
  --animate-button-draw-check: button-draw 180ms cubic-bezier(0.2, 0, 0, 1) 180ms both;
  --animate-spinner-rotate: spinner-rotate 0.9s linear infinite;
  --animate-spinner-dash: spinner-dash 1.5s ease-in-out infinite;
  --animate-spinner-ticks: spinner-rotate 0.8s steps(8, end) infinite;
  --animate-spinner-pulse: spinner-pulse 1.6s ease-in-out infinite;
  --animate-progress-slide: progress-slide 1.6s cubic-bezier(0.65, 0, 0.35, 1) infinite;
  --animate-checkbox-draw: button-draw 200ms cubic-bezier(0.2, 0, 0, 1) 40ms both;
  --animate-button-shake: button-shake 320ms cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
  --animate-avatar-badge-pulse: avatar-badge-pulse 700ms cubic-bezier(0.215, 0.61, 0.355, 1) both;
  --animate-menu-blink: menu-blink 120ms steps(1, end) both;
  --animate-input-otp-wave: input-otp-wave 1.2s ease-in-out infinite;
  --animate-input-otp-pulse: input-otp-pulse 1.2s ease-in-out infinite;
  --animate-input-otp-pop: input-otp-pop 360ms cubic-bezier(0.23, 1, 0.32, 1) both;
  --animate-empty-in: empty-in 480ms cubic-bezier(0.23, 1, 0.32, 1) var(--empty-delay, 0ms) both;
  --animate-message-in: message-in 420ms linear(0, 0.015 2%, 0.0532 4%, 0.1065 6%, 0.1686 8%, 0.2351 10%, 0.3363 13%, 0.4332 16%, 0.5495 20%, 0.648 24%, 0.7287 28%, 0.807 33%, 0.8646 38%, 0.9128 44%, 0.9447 50%, 0.968 57%, 0.9834 65%, 0.9924 74%, 0.9975 85%, 1) both;
  --animate-video-player-flash: video-player-flash 650ms cubic-bezier(0.23, 1, 0.32, 1) both;
}

:root {
  --destructive-foreground: oklch(0.985 0 0);
  --success: oklch(0.527 0.154 150);
  --success-foreground: oklch(0.985 0 0);
  --info: oklch(0.546 0.215 262);
  --info-foreground: oklch(0.985 0 0);
  --warning: oklch(0.555 0.163 49);
  --warning-foreground: oklch(0.985 0 0);
}

.dark {
  --destructive-foreground: oklch(0.205 0 0);
  --success: oklch(0.792 0.209 151.7);
  --success-foreground: oklch(0.205 0 0);
  --info: oklch(0.707 0.165 254.6);
  --info-foreground: oklch(0.205 0 0);
  --warning: oklch(0.828 0.189 84.4);
  --warning-foreground: oklch(0.205 0 0);
}

@keyframes message-in {
  from {
    opacity: 0;
    translate: 0 0.5rem;
    scale: 0.96;
  }
}

@keyframes video-player-flash {
  from {
    opacity: 0;
    scale: var(--video-player-flash-from, 0.9);
  }
  20%, 55% {
    opacity: 1;
    scale: 1;
  }
  to {
    opacity: 0;
    scale: var(--video-player-flash-to, 1.08);
  }
}

@keyframes empty-in {
  from {
    opacity: 0;
    translate: 0 0.375rem;
    filter: blur(2px);
  }
}

@keyframes shimmer {
  from {
    translate: calc(-100% * var(--skeleton-dir, 1)) 0;
  }
  to {
    translate: calc(100% * var(--skeleton-dir, 1)) 0;
  }
}

@keyframes skeleton-pulse {
  0%, 100% {
    opacity: 0;
  }
  50% {
    opacity: 0.5;
  }
}

@keyframes button-state-in {
  from {
    opacity: 0;
    transform: perspective(220px) rotateX(90deg) translateY(0.75rem);
  }
  to {
    opacity: 1;
    transform: perspective(220px) rotateX(0) translateY(0);
  }
}

@keyframes button-state-out {
  from {
    opacity: 1;
    transform: perspective(220px) rotateX(0) translateY(0);
  }
  50% {
    opacity: 0;
  }
  to {
    opacity: 0;
    transform: perspective(220px) rotateX(-90deg) translateY(-0.75rem);
  }
}

@keyframes spinner-rotate {
  to {
    rotate: 360deg;
  }
}

@keyframes spinner-dash {
  0% {
    stroke-dasharray: 1 60;
    stroke-dashoffset: 0;
  }
  50% {
    stroke-dasharray: 34 60;
    stroke-dashoffset: -12;
  }
  100% {
    stroke-dasharray: 34 60;
    stroke-dashoffset: -56;
  }
}

@keyframes progress-slide {
  from {
    translate: calc(-100% * var(--progress-dir, 1)) 0;
  }
  to {
    translate: calc(250% * var(--progress-dir, 1)) 0;
  }
}

@keyframes spinner-pulse {
  0%, 100% {
    opacity: 1;
  }
  50% {
    opacity: 0.4;
  }
}

@keyframes button-draw {
  to {
    stroke-dashoffset: 0;
  }
}

@keyframes avatar-badge-pulse {
  from {
    scale: 1;
    opacity: 0.5;
  }
  to {
    scale: 2.6;
    opacity: 0;
  }
}

@keyframes menu-blink {
  0% {
    background-color: transparent;
  }
  50%, 100% {
    background-color: var(--menu-blink, var(--color-accent));
  }
}

@keyframes input-otp-wave {
  0%, 60%, 100% {
    translate: 0 0;
    opacity: 1;
  }
  30% {
    translate: 0 -0.18em;
    opacity: 0.45;
  }
}

@keyframes input-otp-pulse {
  0%, 100% {
    opacity: 1;
  }
  50% {
    opacity: 0.45;
  }
}

@keyframes input-otp-pop {
  0% {
    scale: 1;
  }
  40% {
    scale: 1.16;
  }
  100% {
    scale: 1;
  }
}

@keyframes button-shake {
  0%, 100% {
    translate: 0;
  }
  20% {
    translate: -3px;
  }
  40% {
    translate: 3px;
  }
  60% {
    translate: -2px;
  }
  80% {
    translate: 2px;
  }
}

@utility text-hero {
  font-size: min(calc((100vw - 1.5rem) / 15.75), 2.6875rem);
  line-height: 1.3;
}

@utility border-hairline {
  border-width: var(--hairline);
}

:root {
  --hairline: 1px;
}

@media (min-resolution: 1.5dppx) {
  :root {
    --hairline: calc(1px / 1.5);
  }
}

@media (min-resolution: 2dppx) {
  :root {
    --hairline: 0.5px;
  }
}

@media (min-resolution: 3dppx) {
  :root {
    --hairline: calc(1px / 3);
  }
}

@media (min-resolution: 4dppx) {
  :root {
    --hairline: 0.25px;
  }
}

@layer base {
  body {
    position: relative;
  }
  :where(a, button, input, label, select, summary, textarea, [role="button"]) {
    touch-action: manipulation;
  }
}
```

## AI assistants

Every page is available as Markdown, so assistants get the full source, examples and API without scraping. Use the Copy page menu at the top of any page, or point your assistant at these files.

- `https://hextaui.com/llms.txt` lists every page with a short description.
- `https://hextaui.com/llms-full.txt` has every page in one file.
- Add `.md` to any docs URL for that page, like `https://hextaui.com/docs/button.md`.

For the best results, connect the [HextaUI MCP server](https://hextaui.com/docs/mcp). Assistants search the docs, read each API and get install commands without leaving your editor.

With the namespace above, the shadcn MCP server lets assistants like Claude Code, Cursor and Codex browse and install HextaUI components directly.

```bash
npx shadcn@latest mcp init --client claude
```

---

# MCP server

> Connect Claude Code, Cursor, VS Code and other AI assistants to HextaUI, so they search the docs, read each API and install components for you.

Docs: https://hextaui.com/docs/mcp
Markdown: https://hextaui.com/docs/mcp.md

The HextaUI MCP server gives assistants the same docs you read here: what each component is for, its props and data attributes, keyboard support, working examples and the command that installs it. Assistants stop guessing at shadcn/ui props and use what HextaUI actually ships.

It is a hosted, read-only server at `https://hextaui.com/mcp`. There is nothing to install and no API key. It reads the docs of the version on this site, so it is always current.

## Setup

Add the server to your assistant, then ask it to build something with HextaUI.

### Claude Code

```bash
claude mcp add --transport http hextaui https://hextaui.com/mcp
```

### Cursor

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "hextaui": {
      "url": "https://hextaui.com/mcp"
    }
  }
}
```

### VS Code

```json title=".vscode/mcp.json"
{
  "servers": {
    "hextaui": {
      "type": "http",
      "url": "https://hextaui.com/mcp"
    }
  }
}
```

### Codex

```toml title="~/.codex/config.toml"
[mcp_servers.hextaui]
url = "https://hextaui.com/mcp"
```

### Windsurf

```json title="~/.codeium/windsurf/mcp_config.json"
{
  "mcpServers": {
    "hextaui": {
      "serverUrl": "https://hextaui.com/mcp"
    }
  }
}
```

### Other clients

Any client that supports remote servers over Streamable HTTP can use the URL directly. For a client that only runs local servers, bridge it with `mcp-remote`.

```json
{
  "mcpServers": {
    "hextaui": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hextaui.com/mcp"]
    }
  }
}
```

## Tools

Every tool is read-only. Installing is left to your assistant, which runs the shadcn CLI command in your project like you would.

- `search_docs` finds components, examples, props and data attributes from plain language, like “confirm before delete” or a prop name.
- `list_components` lists every component, hook and utility by category.
- `get_component` returns a page's full docs: install command, usage, examples, keyboard, accessibility and API reference.
- `get_component_api` returns only the API reference and keyboard support.
- `get_examples` returns the code of any example on a page.
- `get_component_source` returns the source files the CLI would install.
- `get_install_command` builds one shadcn command for several components, for npm, pnpm, yarn or bun.
- `get_setup` returns the [installation](https://hextaui.com/docs/installation) guide and the conventions generated code should follow.

The server also exposes each page as a `hextaui://docs/{slug}` resource, and a `build-ui` prompt that walks an assistant from picking components to installing them.

## Try it

- Build a settings page with HextaUI: profile form, notification switches and a danger zone.
- Which HextaUI component should I use for a list of files with checkboxes?
- Replace this modal with the HextaUI dialog and keep the form working.
- Add a chat view with HextaUI message bubbles that scrolls to new messages.

Prefer the shadcn MCP server? Register the [@hextaui namespace](https://hextaui.com/docs/installation#namespace) and it can browse and install HextaUI components and examples too.

---

# Accordion

> Stacked headings that each reveal a panel, with height motion you can reverse mid-way and panels that stay searchable while closed.

Docs: https://hextaui.com/docs/accordion
Markdown: https://hextaui.com/docs/accordion.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/accordion.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/accordion.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@/components/ui/accordion"
```

```tsx
<Accordion defaultValue={["item-1"]}>
  <AccordionItem value="item-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>
      Yes. It follows the WAI-ARIA accordion pattern.
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

## Composition

```text
Accordion
└── AccordionItem
    ├── AccordionTrigger
    └── AccordionContent
```

## Examples

### Outline

Items share one bordered surface, with the outer corners rounded.

### Separated

Each item is its own card.

### Ghost

No borders. Triggers get a soft fill on hover and when open.

### Multiple

Set `multiple` to let more than one item stay open.

### Disabled

Disable a single item with `disabled` on `<AccordionItem />`, or the whole accordion on the root.

### Controlled

Pass `value` and `onValueChange` to keep the open items in your own state.

### Custom icon

Pass any element to `icon`. Style its open state with `group-data-panel-open/accordion-trigger`.

### Leading icons

Icons before the label are sized and aligned for you. `icon={null}` removes the chevron.

### Long content

Long titles wrap while the icon stays on the first line. Closed panels stay searchable, so Cmd/Ctrl+F for “retention” opens this one.

### Nested

An inner accordion keeps its own variant, focus styles and arrow-key navigation.

### Right to left

Content, icons and the open motion follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | Opens or closes the focused item. |
| `↓` | Moves focus to the next trigger. |
| `↑` | Moves focus to the previous trigger. |
| `Home` | Moves focus to the first trigger. |
| `End` | Moves focus to the last trigger. |
| `Tab` | Moves focus into the open panel, then on to the next trigger. |

## API reference

Built on the Base UI accordion. Every part accepts the props of the primitive it wraps.

### Accordion

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "separated" \| "ghost"` | `"default"` |  |
| `multiple` | `boolean` | `false` | Allow more than one item to be open. |
| `value` | `Value[]` | – |  |
| `defaultValue` | `Value[]` | – |  |
| `onValueChange` | `(value: Value[], details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |
| `hiddenUntilFound` | `boolean` | `true` | Keep closed panels findable with the browser’s page search. |
| `keepMounted` | `boolean` | `false` | Ignored while hiddenUntilFound is on. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="accordion"` | Target the root in CSS. |
| `data-variant` | The current variant. |
| `data-disabled` | Present when the accordion is disabled. |

### AccordionItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` | – | Generated automatically when omitted. |
| `disabled` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="accordion-item"` | Target items in CSS. |
| `data-open` | Present when the item is open. |
| `data-disabled` | Present when the item is disabled. |
| `data-index` | The item’s position, starting at 0. |

### AccordionTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode \| null` | `<IconChevronDown />` | null removes the icon. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="accordion-trigger"` | Target triggers in CSS. |
| `data-panel-open` | Present when its panel is open. Style the icon with group-data-panel-open/accordion-trigger. |
| `data-disabled` | Present when the item is disabled. |

### AccordionContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | – | Applied to the inner wrapper, so padding never fights the height animation. |
| `keepMounted` | `boolean` | `false` |  |
| `hiddenUntilFound` | `boolean` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="accordion-content"` | Target panels in CSS. |
| `data-open` | Present when the panel is open. |
| `data-starting-style` | Present while the panel animates in. |
| `data-ending-style` | Present while the panel animates out. |
| `data-settled` | Present once the panel is fully open. It stops clipping then, so focus rings inside a nested accordion show in full. |
| `--accordion-panel-height` | The panel’s measured height, used for the height animation. |

---

# Alert

> Inline messages for status and feedback, with a neutral surface, a colored icon and a dismiss that collapses smoothly.

Docs: https://hextaui.com/docs/alert
Markdown: https://hextaui.com/docs/alert.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/alert.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/alert.tsx`, `components/ui/button.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Alert,
  AlertAction,
  AlertClose,
  AlertDescription,
  AlertTitle,
} from "@/components/ui/alert"
```

```tsx
<Alert>
  <IconTerminal2 />
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>
    You can add components to your app using the CLI.
  </AlertDescription>
</Alert>
```

## Composition

```text
Alert
├── AlertTitle
├── AlertDescription
├── AlertAction
└── AlertClose
```

## Examples

### Variants

`variant` colors only the icon, so the surface stays neutral and status reads at a glance without shouting.

### Soft

`appearance="soft"` drops the border and tints the whole surface with the variant color.

### Partial content

Title only, description only and no icon all line up without extra classes. The grid places each part in its own column.

### Actions

Put buttons in `<AlertAction />`. They align with the first line of the title, even when it wraps.

### Dismissible

Add `<AlertClose />` to let people dismiss it. The alert collapses smoothly and the content below slides up. Dismiss it from the keyboard and focus moves to the next control, here “Reset”.

### Controlled

Pass `open` and `onOpenChange` to drive it from your own state. It animates both in and out.

### Cancel a dismiss

Call `event.preventDefault()` in the close button’s `onClick` to keep the alert open, for example to ask for confirmation first.

### Inserted after load

Alerts that mount after the page has loaded fade and slide in, and screen readers announce them. Alerts already in the server HTML appear without motion.

### Rich content

Inline icons and links inside the description keep their own style. Use `render` to give the title a heading level.

### Right to left

The icon, content and close button mirror with the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus to links, actions and the close button inside the alert. |
| `Enter` `Space` | Activates the focused close button. Once the alert has collapsed, focus moves to the next focusable element, or the previous one when nothing follows. |

## Accessibility

- `destructive` and `warning` alerts get `role="alert"` and are announced right away. Every other variant gets `role="status"` and waits for a pause.
- The close button is labelled “Dismiss”. Pass `aria-label` to translate it.
- Focus is never lost when a focused alert closes.
- With reduced motion on, alerts appear and disappear instantly.

## API reference

Every part accepts the attributes of the element it renders. The variants are exported as `alertVariants` for styling other elements the same way.

### Alert

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive" \| "success" \| "info" \| "warning"` | `"default"` | Colors the icon. destructive and warning are announced assertively. |
| `appearance` | `"outline" \| "soft"` | `"outline"` |  |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `true` |  |
| `onOpenChange` | `(open: boolean) => void` | – | Called when the close button is pressed. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert"` | Target the alert in CSS. |
| `data-variant` | The current variant. |
| `data-appearance` | The current appearance. |
| `data-ending-style` | Present while the alert collapses after a dismiss. |

### AlertTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-title"` | Target titles in CSS. |

### AlertDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-description"` | Target descriptions in CSS. Plain links inside are underlined for you. |

### AlertAction

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-action"` | Target the action area in CSS. |

### AlertClose

A ghost `<Button />` that closes the nearest alert. It accepts every Button prop and must be used inside `<Alert />`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Dismiss"` |  |
| `children` | `ReactNode` | `<IconX />` |  |
| `onClick` | `(event: MouseEvent) => void` | – | Call event.preventDefault() to keep the alert open. |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-close"` | Target the close button in CSS. |

---

# Alert dialog

> A confirmation dialog for destructive or important actions that waits for async work, and becomes a bottom sheet on phones.

Docs: https://hextaui.com/docs/alert-dialog
Markdown: https://hextaui.com/docs/alert-dialog.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/alert-dialog.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/alert-dialog.tsx`, `components/ui/sheet.tsx`, `components/ui/button.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from "@/components/ui/alert-dialog"
```

```tsx
<AlertDialog>
  <AlertDialogTrigger render={<Button variant="outline" />}>
    Delete
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this project?</AlertDialogTitle>
      <AlertDialogDescription>This can’t be undone.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Delete</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

## Composition

```text
AlertDialog
├── AlertDialogTrigger
└── AlertDialogContent
    ├── AlertDialogHeader
    │   ├── AlertDialogMedia
    │   ├── AlertDialogTitle
    │   └── AlertDialogDescription
    └── AlertDialogFooter
        ├── AlertDialogCancel
        └── AlertDialogAction
```

## Examples

### Async action

Return a promise from the `onClick` of `<AlertDialogAction />`. The button shows a spinner and the dialog can’t be closed until the promise settles. It closes when it resolves and stays open when it rejects, so people can try again.

### Media

`<AlertDialogMedia />` places an icon beside the title on desktop and above it on phones. Use `variant="destructive"` for destructive actions.

### Small

`size="sm"` centers the content and lays the buttons out side by side, for short questions.

### Detached triggers

Create a handle with `createAlertDialogHandle()` to share one dialog between many triggers. Each trigger passes its own `payload`, which the dialog reads through a render function.

### Controlled

Pass `open` and `onOpenChange` to open it from code, without a trigger. Focus still lands on Cancel.

### Nested

A dialog opened from inside another stacks on top. The parent scales back while the child is open and comes forward again when it closes.

### Long content

Content taller than the screen scrolls inside the dialog while the page stays locked.

### Right to left

Pass `dir` to the content as well, because it renders in a portal outside your RTL container. Arrow keys in the footer follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | On the trigger, opens the dialog and moves focus to Cancel. |
| `Tab` `Shift+Tab` | Moves focus between controls. Focus stays inside. |
| `←` `→` `↑` `↓` | Moves between the footer buttons and wraps around. Left and right follow the reading direction. |
| `Esc` | Closes the dialog and returns focus to the trigger. Ignored while an async action is running. |

## Accessibility

- The content has `role="alertdialog"` and is labelled by its title and described by its description.
- Focus starts on `<AlertDialogCancel />`, the least destructive choice. Pass `initialFocus` to change it.
- Clicking the backdrop doesn’t close it, so a decision is never dismissed by accident. Set `disablePointerDismissal={false}` to allow it.
- On phones it becomes a bottom sheet that can be swiped down to cancel. While an action is pending, swiping, Esc and Cancel are blocked and the buttons stay focusable.
- With reduced motion on, it fades instead of scaling.

## API reference

Built on the Base UI drawer, through `<Sheet />`. Every part accepts the props of the primitive or element it wraps.

### AlertDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – | Not called for closes blocked by a pending action. |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the open or close animation. |
| `disablePointerDismissal` | `boolean` | `true` | Keeps the dialog open on backdrop clicks. |
| `handle` | `AlertDialogHandle<Payload>` | – | Connects detached triggers. |
| `actionsRef` | `RefObject<{ close, unmount }>` | – | Close or unmount the dialog imperatively. |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – |  |

### AlertDialogTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `AlertDialogHandle<Payload>` | – |  |
| `payload` | `Payload` | – | Passed to the dialog’s render function. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-trigger"` | Target triggers in CSS. |
| `data-popup-open` | Present while its dialog is open. |

### AlertDialogContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"default" \| "sm"` | `"default"` |  |
| `initialFocus` | `boolean \| RefObject \| (openType) => HTMLElement \| boolean` | `Cancel button` |  |
| `finalFocus` | `boolean \| RefObject \| (closeType) => HTMLElement \| boolean` | `The trigger` |  |
| `dir` | `"ltr" \| "rtl"` | – | Set it when the dialog should be right to left. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-content"` | Target the dialog in CSS. |
| `data-size` | The current size. |
| `data-open` | Present while open. |
| `data-starting-style` | Present while the dialog animates in. |
| `data-ending-style` | Present while the dialog animates out. |
| `data-nested-drawer-open` | Present while a nested dialog is open on top. |
| `data-swiping` | Present while it is being swiped on a phone. |
| `--nested-drawers` | How many dialogs are open on top of this one. |

### AlertDialogHeader

A `<div>` that stacks the media, title and description.

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-header"` | Target the header in CSS. |

### AlertDialogMedia

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-media"` | Target the media in CSS. |

### AlertDialogTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<h2>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-title"` | Target the title in CSS. |

### AlertDialogDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` | Use render={<div />} when it holds several paragraphs. |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-description"` | Target the description in CSS. |

### AlertDialogFooter

A `<div>` for the buttons. Buttons stack full width on phones, and arrow keys move between them.

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-footer"` | Target the footer in CSS. |

### AlertDialogAction

A `<Button />` that closes the dialog when clicked. It accepts every Button prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onClick` | `(event) => void \| PromiseLike<unknown>` | – | Return a promise to show a spinner and keep the dialog open until it settles. Call event.preventDefault() to keep it open. |
| `variant` | `ButtonVariant` | `"default"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-action"` | Target actions in CSS. |

### AlertDialogCancel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ButtonVariant` | `"outline"` |  |
| `size` | `ButtonSize` | – |  |
| `disabled` | `boolean` | – | Also disabled while an action is pending. |

| Attribute | Description |
| --- | --- |
| `data-slot="alert-dialog-cancel"` | Target the cancel button in CSS. It receives initial focus. |
| `data-disabled` | Present while disabled. |

### AlertDialogPortal and AlertDialogOverlay

`<AlertDialogContent />` already renders both. Use them only when composing a custom popup.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `false` | On the portal, keeps the dialog in the DOM while closed. |

### createAlertDialogHandle

Returns a handle that connects `<AlertDialogTrigger />` elements anywhere on the page to one `<AlertDialog />`. Type the payload with a generic: `createAlertDialogHandle<{ name: string }>()`.

---

# Aspect ratio

> A box that holds its shape before media loads, shimmers while loading, fades the media in and falls back when it fails.

Docs: https://hextaui.com/docs/aspect-ratio
Markdown: https://hextaui.com/docs/aspect-ratio.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/aspect-ratio.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/aspect-ratio.tsx`, `components/ui/skeleton.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { AspectRatio } from "@/components/ui/aspect-ratio"
```

```tsx
<AspectRatio ratio={16 / 9} className="rounded-lg">
  <img src="/photo.jpg" alt="Sunset over mountains" />
</AspectRatio>
```

## Examples

### Ratios

`ratio` takes a number, a `"w/h"` string or a `"w:h"` string.

### Slow load

The box holds its shape and shimmers until the image arrives, then the image fades in, so nothing below it moves. Press Reload to watch it again.

### Broken image

When the image fails, the browser’s broken-image glyph is hidden and a fallback icon is shown instead. Pass `fallback` to replace it, or `fallback={null}` to show nothing.

### Overlay

Absolutely positioned children sit on top of the media. The box clips nothing, so focus rings on overlay links stay visible.

### Without placeholder

`placeholder={false}` turns off the loading shimmer, the fade-in and the fallback, for the plain shadcn behavior.

### Responsive

Override the ratio at a breakpoint with an aspect class. This one is square on small screens and `md:aspect-video` from md up.

### Inside a centered flex column

The box is full width by default, so it fills the column instead of collapsing to zero when the parent centers its children.

### Text content

Children that aren’t media get the box and nothing else. Position them yourself.

### As a figure

Keep captions outside the box so they don’t change the ratio.

### Invalid ratio

`0`, negative numbers and unparsable strings fall back to a square and log a warning in development.

### Right to left

Overlays positioned with logical properties like start-3 follow the reading direction.

## Accessibility

- The box is `aria-busy` while its media loads.
- The fallback is decorative and hidden from assistive tech. The image’s `alt` text stays available when it fails to load, so always write one.
- With reduced motion on, media appears without fading.

## API reference

Accepts every attribute of the element it renders. Media placed directly inside, an `<img>`, `<picture>` or `<video>`, fills the box with `object-cover` and inherits its radius.

### AspectRatio

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ratio` | `` number \| `${number}/${number}` \| `${number}:${number}` `` | `1` |  |
| `placeholder` | `boolean` | `true` | Shows a shimmer while the media loads and a fallback when it fails. |
| `fallback` | `ReactNode` | `<IconPhotoOff />` | Shown when the media fails. null shows nothing. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="aspect-ratio"` | Target the box in CSS. |
| `data-state` | loading, loaded or error. Set only when placeholder is on and the box holds media. |
| `aria-busy` | Present while the media loads. |
| `--ratio` | The parsed ratio as a number. |
| `data-slot="aspect-ratio-placeholder"` | The shimmer shown while loading or after an error. |
| `data-slot="aspect-ratio-fallback"` | The wrapper around the fallback. |

### parseAspectRatio

`parseAspectRatio(ratio)` turns any accepted ratio into a number, falling back to `1`. Use it to size other elements the same way. The `AspectRatioValue` and `AspectRatioProps` types are exported too.

---

# Attachment

> File and image cards for uploads, with progress, states, actions, a full-card trigger and names that keep their extension.

Docs: https://hextaui.com/docs/attachment
Markdown: https://hextaui.com/docs/attachment.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/attachment.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/attachment.tsx`, `components/ui/aspect-ratio.tsx`, `components/ui/skeleton.tsx`, `components/ui/button.tsx`, `components/ui/progress.tsx`, `components/ui/scroll-area.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from "@/components/ui/attachment"
```

```tsx
<Attachment>
  <AttachmentMedia>
    <IconFileText />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>report.pdf</AttachmentTitle>
    <AttachmentDescription>PDF · 2.4 MB</AttachmentDescription>
  </AttachmentContent>
  <AttachmentActions>
    <AttachmentAction aria-label="Remove report.pdf">
      <IconX />
    </AttachmentAction>
  </AttachmentActions>
</Attachment>
```

## Composition

```text
Attachment
├── AttachmentMedia
├── AttachmentContent
│   ├── AttachmentTitle
│   └── AttachmentDescription
├── AttachmentActions
│   └── AttachmentAction
└── AttachmentTrigger

AttachmentGroup
└── Attachment
```

## Examples

### Image

`variant="image"` on `<AttachmentMedia />` shows a square thumbnail that shimmers while it loads. Set `orientation="vertical"` for a tile with the preview on top.

### States

`state` covers the whole upload lifecycle. Idle files get a dashed border, uploading and processing titles shimmer, and errors turn the media and description red.

### Upload flow

Pass `progress` while `state="uploading"` to draw a thin progress bar along the bottom edge. Image previews stay dimmed until the upload is done.

### Sizes

`size` scales the padding, media and text together, and keeps the inner corners concentric with the card.

### Long names

Long file names truncate before the extension, so people can still tell a .pdf from a .zip. Hover the name to read it in full.

### Group

`<AttachmentGroup />` lays attachments out in a row that scrolls sideways, with edges that fade and items that snap into place.

### Trigger

`<AttachmentTrigger />` makes the whole card clickable, for example to open a preview or a link, while the actions on it stay independent. Give it an `aria-label`.

### Composer

Files added after the page loads pop in, and the rest of the row slides over smoothly when one is removed.

### Broken image

When an image preview fails to load, it falls back to a file icon.

### Stress

Hostile names in a narrow column, a random state every 60 ms, and 200 items in one group. Nothing overflows and the layout holds.

### Right to left

Media, content and actions mirror, and the progress bar fills from the start edge.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus to each action, then to the trigger. Hidden actions on vertical tiles appear when focus enters the card. |
| `Enter` `Space` | Activates the focused action or trigger. |

## Accessibility

- While uploading, the progress bar has `role="progressbar"` and is labelled by the title.
- String titles get a `title` attribute with the full name, so truncated names can still be read.
- Icon-only actions and the trigger have no text, so always give them an `aria-label` that names the file.
- With reduced motion on, attachments appear without popping in, the progress bar jumps instead of easing, and groups reflow instantly.

## API reference

Every part except the group, the action and the trigger renders a plain element and accepts its attributes. The card styles are exported as `attachmentVariants`.

### Attachment

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `"idle" \| "uploading" \| "processing" \| "error" \| "done"` | `"done"` |  |
| `progress` | `number` | – | 0 to 100. Shown only while uploading, and clamped to that range. |
| `size` | `"default" \| "sm" \| "xs"` | `"default"` |  |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="attachment"` | Target the card in CSS. |
| `data-state` | The current state. |
| `data-size` | The current size. |
| `data-orientation` | The current orientation. |
| `data-slot="attachment-progress"` | The progress bar, present while uploading. |
| `--attachment-radius` | The card’s corner radius. Inner corners are derived from it. |

### AttachmentMedia

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"icon" \| "image"` | `"icon"` | image wraps its child in a square AspectRatio with a file icon fallback. |

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-media"` | Target the media in CSS. |
| `data-variant` | The current variant. |

### AttachmentContent

A `<div>` that holds the title and description and takes the remaining width.

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-content"` | Target the content in CSS. |

### AttachmentTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | A string is split so its extension never truncates. |
| `title` | `string` | `children` | Shown on hover. Defaults to the full name. |
| `id` | `string` | – | Generated when omitted. The progress bar is labelled by it. |

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-title"` | Target the title in CSS. |

### AttachmentDescription

A single-line `<span>` for the size, type or status. It truncates when space runs out.

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-description"` | Target the description in CSS. |

### AttachmentActions

A `<div>` for the action buttons. On vertical tiles it floats over the preview and, on devices with a mouse, appears on hover or focus.

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-actions"` | Target the actions in CSS. |

### AttachmentAction

A `<Button />` that sits above the trigger. It accepts every Button prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ButtonVariant` | `"ghost"` |  |
| `size` | `ButtonSize` | `"icon-xs"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-action"` | Target actions in CSS. |

### AttachmentTrigger

An invisible layer that covers the whole card. Compose it with a dialog trigger, a link or any button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button type="button">` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-trigger"` | Target the trigger in CSS. |

### AttachmentGroup

A horizontal `<ScrollArea />` that snaps to each attachment and animates the row when items are added or removed. It accepts every ScrollArea prop except `scrollbars`.

| Attribute | Description |
| --- | --- |
| `data-slot="attachment-group"` | Target the group in CSS. |
| `data-slot="attachment-group-list"` | The row that holds the attachments. |

---

# Avatar

> User photos with an initials fallback, status badges and stacked groups that collapse into a count.

Docs: https://hextaui.com/docs/avatar
Markdown: https://hextaui.com/docs/avatar.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/avatar.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/avatar.tsx` into your project. Their source is in this page's Markdown.

## Usage

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

```tsx
<Avatar>
  <AvatarImage src="/ada.jpg" alt="" />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>
```

## Composition

```text
Avatar
├── AvatarImage
├── AvatarFallback
└── AvatarBadge

AvatarGroup
├── Avatar
└── AvatarGroupCount
```

## Examples

### Sizes and shapes

Five sizes, as circles or squares. Initials and the user icon scale with the box, and square corners step down with the size. An empty `<AvatarFallback />` shows the user icon.

### Loading

Initials show while the photo loads, then the photo fades in over them. A broken photo keeps the fallback. Pass `delay` to wait before showing initials, so fast photos never flash them.

### Initials

`getInitials()` picks the first and last initial. It handles email addresses, emoji, CJK and RTL names, combining marks, and names with no letters at all.

### Status

`<AvatarBadge />` sits on the rim at every size and shape. Set `status` for a colored dot with an accessible label, or pass an icon. Changing the status plays a single pulse.

### Group

`<AvatarGroup />` overlaps its avatars and sets their size and shape. `max` collapses the rest into a count.

### Linked group

Render avatars as links with `render` and give each an `aria-label`. A focused avatar rises above its neighbours so the ring is never cut. Add `<AvatarGroupCount />` yourself when the total comes from your data.

### Layout

Avatars never shrink in tight rows. A size class like size-20 scales the initials and badge with it, and long initials never overflow.

### Right to left

The badge stays on the end corner, which is the left in RTL, and groups overlap from the right.

## Keyboard

Avatars aren’t focusable on their own. Rendered as a link or button they get the usual keys.

| Key | Action |
| --- | --- |
| `Tab` | Moves focus to the next linked avatar. |
| `Enter` | Follows the focused link. |

## Accessibility

- Use `alt=""` when the person’s name is already next to the avatar, and their name as the alt text when it isn’t.
- Badges with a `status` are announced as “Online”, “Away”, “Busy” or “Offline”. Offline is drawn as a ring, so the status never relies on color alone.
- Groups have `role="group"`. The count reads as “3 more”, not “+3”.
- With reduced motion on, photos appear without fading and status changes don’t pulse.

## API reference

Built on the Base UI avatar. Every part accepts the attributes of the element it renders. The styles are exported as `avatarVariants` and `avatarBadgeVariants`.

### Avatar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"xs" \| "sm" \| "default" \| "lg" \| "xl"` | `"default"` | Inherited from the group when omitted. |
| `shape` | `"circle" \| "square"` | `"circle"` | Inherited from the group when omitted. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="avatar"` | Target avatars in CSS. |
| `data-size` | The resolved size. |
| `data-shape` | The resolved shape. |
| `--avatar-radius` | The corner radius, shared by every layer. |

### AvatarImage

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | – |  |
| `alt` | `string` | – |  |
| `onLoadingStatusChange` | `(status: "idle" \| "loading" \| "loaded" \| "error") => void` | – |  |
| `keepMounted` | `boolean` | `false` | Load the image in place instead of preloading it, for loading="lazy" or next/image. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<img>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="avatar-image"` | Target images in CSS. |
| `data-loading` | Present while the image loads. |
| `data-error` | Present when the image failed to load. |
| `data-starting-style` | Present while the image fades in. |
| `data-ending-style` | Present while the image fades out. |

### AvatarFallback

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `<IconUser />` | Empty or whitespace shows the user icon. |
| `delay` | `number` | `0` | Milliseconds to wait before showing it. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="avatar-fallback"` | Target fallbacks in CSS. |
| `data-ready` | false until the delay has passed. |

### AvatarBadge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"online" \| "away" \| "busy" \| "offline"` | – | Colors the dot and labels it for assistive tech. Without it the badge uses the primary color. |
| `children` | `ReactNode` | – | An icon inside the badge. Hidden at the xs and sm sizes. |

| Attribute | Description |
| --- | --- |
| `data-slot="avatar-badge"` | Target badges in CSS. |
| `data-status` | The current status. |
| `data-slot="avatar-badge-pulse"` | The pulse played after a status change. |

### AvatarGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"xs" \| "sm" \| "default" \| "lg" \| "xl"` | `"default"` |  |
| `shape` | `"circle" \| "square"` | `"circle"` |  |
| `max` | `number` | – | How many items to show, including the count. Values below 2 are raised to 2. |

| Attribute | Description |
| --- | --- |
| `data-slot="avatar-group"` | Target groups in CSS. |
| `data-size` | The group’s size. |

### AvatarGroupCount

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | – | Shown as +3, or 99+ above 99. |
| `children` | `ReactNode` | – | Replaces the count, for example with an icon. |
| `size` | `"xs" \| "sm" \| "default" \| "lg" \| "xl"` | – | Inherited from the group when omitted. |
| `shape` | `"circle" \| "square"` | – | Inherited from the group when omitted. |

| Attribute | Description |
| --- | --- |
| `data-slot="avatar-group-count"` | Target the count in CSS. |
| `data-size` | The resolved size. |
| `data-shape` | The resolved shape. |

### getInitials

`getInitials(name, max = 2)` returns up to `max` uppercase initials: the first word’s and the last word’s. For an email address it uses the part before the `@`. It returns an empty string when the name has no letters, numbers or emoji, so the fallback shows the user icon.

---

# Badge

> Status labels with colored dots, removable tags that slide closed and counts that roll to their new value.

Docs: https://hextaui.com/docs/badge
Markdown: https://hextaui.com/docs/badge.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/badge.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/badge.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Badge,
  BadgeClose,
  BadgeCount,
  BadgeDot,
} from "@/components/ui/badge"
```

```tsx
<Badge variant="success">
  <BadgeDot />
  Paid
</Badge>
```

## Composition

```text
Badge
├── BadgeDot
├── BadgeCount
└── BadgeClose
```

## Examples

### Variants and appearances

The default `outline` appearance keeps a neutral surface and puts the status color on the dot or icon. Use `appearance="solid"` when the badge needs to stand out.

### Sizes

`sm`, `default` and `lg`. Icons, dots, the close button and counts scale with the badge.

### Removable

Add a `<BadgeClose />` to make a badge removable. It shrinks closed and its neighbours slide into the gap, then focus moves to the next close button. Remove the item from your data in `onOpenChangeComplete` so the exit animation can finish first.

### Controlled

Pass `open` and `onOpenChange` to own the visibility. Setting `open` back to `true` brings the badge back with an enter animation.

### Counts

`<BadgeCount />` rolls only the digits that change, and caps at `max` (99 by default) with a plus sign. Screen readers always hear the real number.

### Interactive

Use `render` to make a badge a link or a button. It gains a hover tint, a press scale and a focus ring. `aria-invalid` shows the error state.

### Long content

A badge never grows wider than its container. Long labels truncate with an ellipsis while icons and the close button stay visible.

### Right to left

Icons, the close button and the collapse animation follow the reading direction. Counts always read left to right.

## Keyboard

These keys apply to `<BadgeClose />`.

| Key | Action |
| --- | --- |
| `Enter` `Space` | Removes the badge. |
| `Backspace` `Delete` | Removes the badge. |
| `Tab` | Moves to the next close button. After a removal, focus lands on the next close button, or the previous one when it was the last. |

## Accessibility

- The close button is named after the badge, so a screen reader announces “Remove design” rather than a bare “Remove”. Pass `aria-label` to override it.
- `<BadgeDot />` is decorative and hidden from assistive tech. Keep the status in the text label.
- `<BadgeCount />` exposes the exact value even when the visible text is capped, like 99+.
- The removal and count animations are skipped when reduced motion is on.

## API reference

`<Badge />` renders a `<span>` and accepts all of its attributes.

### Badge

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "success" \| "info" \| "warning" \| "destructive"` | `"default"` | Colors the dot and icons in outline, or the surface in solid. |
| `appearance` | `"outline" \| "solid"` | `"outline"` |  |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `open` | `boolean` | – | Controlled visibility. |
| `defaultOpen` | `boolean` | `true` |  |
| `onOpenChange` | `(open: boolean) => void` | – | Called when BadgeClose is activated. |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the exit animation finishes. Remove the item from your data here. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="badge"` | Target badges in CSS. |
| `data-variant` | The current variant. |
| `data-appearance` | The current appearance. |
| `data-size` | The current size. |
| `data-ending-style` | Present while the badge animates out. |
| `--badge-accent` | The status color used by dots and icons. Override it for a custom accent. |
| `--badge-height` | The badge height. |
| `--badge-radius` | The corner radius. The close button derives its own radius from it. |

### BadgeDot

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pulse` | `boolean` | `false` | Adds a ping animation for live states. Off when reduced motion is on. |

| Attribute | Description |
| --- | --- |
| `data-slot="badge-dot"` | Target dots in CSS. |
| `data-pulse` | Present when pulse is on. |

### BadgeClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `<IconX />` |  |
| `aria-label` | `string` | – | Overrides the automatic “Remove {label}” name. |
| `onClick` | `(event) => void` | – | Call event.preventDefault() to keep the badge open. |

| Attribute | Description |
| --- | --- |
| `data-slot="badge-close"` | Target the close button in CSS. |

### BadgeCount

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | – | Negative and non-finite values show 0. |
| `max` | `number` | `99` | Values above it show as max+. Pass Infinity for no cap. |
| `duration` | `number` | `600` |  |
| `animated` | `boolean` | `true` |  |
| `trend` | `"auto" \| "up" \| "down" \| "shortest"` | `"auto"` | The direction the digits spin. |
| `locales` | `Intl.LocalesArgument` | – |  |
| `format` | `Intl.NumberFormatOptions` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="badge-count"` | Target counts in CSS. |

---

# Breadcrumb

> A trail of links to the current page that wraps safely, mirrors in right-to-left layouts and expands collapsed segments in place.

Docs: https://hextaui.com/docs/breadcrumb
Markdown: https://hextaui.com/docs/breadcrumb.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/breadcrumb.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react cn
```

Copy `components/ui/breadcrumb.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"
```

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Composition

```text
Breadcrumb
└── BreadcrumbList
    ├── BreadcrumbItem
    │   └── BreadcrumbLink
    ├── BreadcrumbSeparator
    ├── BreadcrumbCollapse
    │   ├── BreadcrumbItem
    │   └── BreadcrumbSeparator
    └── BreadcrumbItem
        └── BreadcrumbPage
```

## Examples

### Basic

### With icons

Icons sit inside links and the current page. Give an icon-only link an `aria-label`.

### Custom separator

Pass any element as `children` of `<BreadcrumbSeparator />` to replace the chevron.

### Dropdown

Render a `<BreadcrumbLink />` as the trigger of a `<DropdownMenu />` to offer sibling pages.

### Collapsed

Wrap middle segments in `<BreadcrumbCollapse />`. They hide behind an ellipsis and slide open in place, and focus moves to the first revealed link. Pass `open` and `onOpenChange` to control it.

### Ellipsis

A static `<BreadcrumbEllipsis />` marks skipped levels. It is hidden from assistive tech unless you make it interactive.

### Link component

Use the `render` prop to swap the anchor for your router's link, like Next.js `<Link />`.

### Long content

Unbroken names wrap instead of overflowing, and segments with a max width truncate.

### Right to left

Separators flip and the collapse animates from the correct side.

## Keyboard

Links and the collapse button are regular tab stops. Separators and a static ellipsis are skipped.

| Key | Action |
| --- | --- |
| `Tab` `Shift + Tab` | Moves between links and the collapse button. |
| `Enter` | Follows the focused link. |
| `Enter` `Space` | On the collapse button, reveals the hidden segments. Once they finish sliding open, focus moves to the first revealed link. |

## API reference

Every part accepts the attributes of the element it renders, plus a `render` prop to swap that element.

### Breadcrumb

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<nav>` | Labelled “Breadcrumb” for assistive tech. |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb"` | The <nav> landmark. |

### BreadcrumbList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<ol>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-list"` | The ordered list. Items wrap onto new lines when space runs out. |

### BreadcrumbItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<li>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-item"` | Target items in CSS. |
| `data-collapsed` | Present while the item is hidden inside a closed BreadcrumbCollapse. |
| `data-breadcrumb-group` | Present on items inside a BreadcrumbCollapse. Shared by every part of the same group. |

### BreadcrumbLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<a>` | Pass your router’s link component here. |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-link"` | Target links in CSS. |

### BreadcrumbPage

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` | Marked with aria-current="page". |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-page"` | The current page, with aria-current="page". |

### BreadcrumbSeparator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `<IconChevronRight />` | Mirrors automatically in right-to-left layouts. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<li>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-separator"` | Presentational and hidden from assistive tech. |
| `data-collapsed` | Present while the separator is hidden inside a closed BreadcrumbCollapse. |
| `data-breadcrumb-group` | Present on separators inside a BreadcrumbCollapse. |

### BreadcrumbEllipsis

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `<IconDots />` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` | Hidden from assistive tech unless render or onClick makes it interactive. |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-ellipsis"` | Target the ellipsis in CSS. |

### BreadcrumbCollapse

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | The items and separators to hide behind the ellipsis. |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` | – |  |
| `label` | `string` | `"Show full path"` | Accessible name of the ellipsis button. |

| Attribute | Description |
| --- | --- |
| `data-slot="breadcrumb-collapse"` | The <li> that holds the ellipsis button. |
| `data-collapsed` | Present on the ellipsis item once the group has opened, which hides it. |

---

# Bubble

> Chat message bubbles with variants, grouped corners, reactions and room for interactive content.

Docs: https://hextaui.com/docs/bubble
Markdown: https://hextaui.com/docs/bubble.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/bubble.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/bubble.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Bubble,
  BubbleContent,
  BubbleGroup,
  BubbleReactions,
} from "@/components/ui/bubble"
```

```tsx
<BubbleGroup>
  <Bubble variant="secondary">
    <BubbleContent>Did the deploy land?</BubbleContent>
  </Bubble>
  <Bubble align="end">
    <BubbleContent>It did.</BubbleContent>
  </Bubble>
</BubbleGroup>
```

## Composition

```text
BubbleGroup
└── Bubble
    ├── BubbleContent
    └── BubbleReactions
```

## Examples

### Variants

Seven treatments, from a strong primary bubble to unframed `ghost` content for assistant replies. `destructive` tints the surface and colors icons inside it.

### Alignment

`align="end"` pushes a bubble to the end of the row for the current user’s messages. It follows the reading direction.

### Group

Wrap consecutive messages from one sender in `<BubbleGroup />`. Corners on the sender side tighten so the run reads as one block, and a lone bubble stays fully round.

### Shapes

Set `shape` on a group to style all of its bubbles, or on a single bubble. `joined` is the default.

### Tail

`shape="tail"` draws a tail on the last bubble of a run, matching the bubble color. Outline and ghost bubbles skip it.

### Reactions

`<BubbleReactions />` overlaps the bubble edge and reserves its own space, so the next row needs no extra gap. Give a static row `role="img"` and a label, or use buttons for interactive reactions.

### Show more

Render a `<Collapsible />` as the bubble content to fold long messages. The bubble grows smoothly and the hidden text stays searchable.

### Tooltip

Render a bubble as a tooltip trigger to show details like the read time. Add `tabIndex` so keyboard users can reach it.

### Popover

Render the content as a `<button>` to make the whole bubble a popover trigger, for example to explain a failed delivery.

### Long content

Unbroken strings, URLs, emoji and CJK text wrap inside the bubble instead of overflowing a narrow column.

### Nested reply

A quoted bubble inside another keeps radii concentric with its parent.

### Right to left

Alignment, joined corners, tails and reactions all mirror in right-to-left layouts.

## Accessibility

- Bubbles are plain containers. Wrap a conversation in a list or a `role="log"` region if new messages should be announced.
- Emoji-only reaction rows need `role="img"` and an `aria-label` that spells out the reactions.
- Interactive content rendered as a button or link gets a focus ring that follows the bubble’s corners.

## API reference

Every part renders a `<div>` by default and accepts its attributes, plus a `render` prop to swap the element.

### Bubble

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "secondary" \| "muted" \| "tinted" \| "outline" \| "ghost" \| "destructive"` | `"default"` |  |
| `align` | `"start" \| "end"` | `"start"` |  |
| `shape` | `"uniform" \| "joined" \| "tail"` | `"joined"` | Inherited from BubbleGroup when not set. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="bubble"` | Target bubbles in CSS. |
| `data-variant` | The current variant. |
| `data-align` | The current alignment. |
| `data-shape` | The resolved shape. |
| `--bubble-bg` | The surface color, also used by the tail. |
| `--bubble-fg` | The text color. |
| `--bubble-border` | The ring color. |
| `--bubble-radius` | The corner radius. |
| `--bubble-radius-joined` | The tighter radius used between grouped bubbles. |
| `--bubble-accent` | Icon color inside the content. Set by destructive. |

### BubbleContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` | Render a <button> or <a> to make it interactive. |

| Attribute | Description |
| --- | --- |
| `data-slot="bubble-content"` | Target the bubble surface in CSS. |

### BubbleGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` | `"uniform" \| "joined" \| "tail"` | – | Applies to every bubble inside the group. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="bubble-group"` | Target groups in CSS. |
| `data-shape` | The group shape, when set. |

### BubbleReactions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom"` | `"bottom"` |  |
| `align` | `"start" \| "end"` | `"end"` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="bubble-reactions"` | Target reaction rows in CSS. |
| `data-side` | The current side. |
| `data-align` | The current alignment. |

---

# Button

> Buttons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.

Docs: https://hextaui.com/docs/button
Markdown: https://hextaui.com/docs/button.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/button.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/button.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Button } from "@/components/ui/button"
```

```tsx
<Button feedback onClick={() => saveSettings()}>
  Save changes
</Button>
```

With `feedback`, return a promise from `onClick` and the button shows loading, then success or error, then resets on its own.

## Examples

### Variants

Six variants. `destructive` is a soft tint so a dangerous action reads clearly without shouting.

### Sizes

Text sizes `xs` to `lg`, and square `icon-*` sizes. Small icon buttons get a larger invisible touch area on touch screens.

### With icon

Mark an icon with `data-icon="inline-start"` or `"inline-end"` and the padding on that side tightens to balance it.

### Disabled

`focusableWhenDisabled` keeps a disabled button in the tab order, so a tooltip or explanation can still be reached by keyboard.

### Custom labels

`loadingLabel`, `successLabel` and `errorLabel` replace the text for each state. Each label flips in while the old one flips out.

### Smooth width

The button eases to the width of each label instead of reserving space for the longest one, so nothing around it jumps.

### Error details

Pass a function to `errorLabel` to show the rejection reason. While the pointer or keyboard focus stays on the button, the error stays on screen.

### Forms

For submit buttons, call `track()` from `useButtonFeedback` in `onSubmit` and spread `buttonProps` on the button. Remove the @ to see the error.

### Icon buttons

Icon sizes swap only the icon for each state and keep their square shape. The aria-label stays the accessible name.

### Feedback on every variant

Filled variants turn green or red when done. `ghost` and `link` only change their text color.

### Controlled loading

Set `loading` yourself when the work is tracked elsewhere. The button stays focusable and announces that it is busy.

### Controlled status

Drive `status` directly, for example from a form library’s submit state.

### As a link

Pass an anchor to `render` and set `nativeButton={false}` so the button keeps link semantics.

### Right to left

Icons and state labels follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | Activates the button. Ignored while a feedback request is in flight. |
| `Tab` | Moves focus. A loading button stays focusable, and focusing an error keeps it on screen until you move away. |

## Accessibility

- Every state change is announced through a polite live region: loading, then the success or error label.
- While loading, the button sets `aria-busy` and stays focusable, so focus is never lost mid-request.
- The spinner appears only after 150ms and then stays for at least 400ms, so fast requests never flash and slow ones never flicker.
- With reduced motion, state labels fade instead of flipping and the error shake is skipped.

## API reference

Built on the Base UI button. It renders a `<button>` and accepts all of its attributes.

### Button

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "secondary" \| "ghost" \| "destructive" \| "link"` | `"default"` |  |
| `size` | `"xs" \| "sm" \| "default" \| "lg" \| "icon-xs" \| "icon-sm" \| "icon" \| "icon-lg"` | `"default"` |  |
| `feedback` | `boolean` | `false` | Track the promise returned from onClick and show its status. |
| `onClick` | `(event) => unknown` | – | Return a promise to drive feedback. |
| `loading` | `boolean` | – | Controlled loading state. |
| `status` | `"idle" \| "loading" \| "success" \| "error"` | – | Controlled status. Takes priority over loading. |
| `onStatusChange` | `(status: ButtonStatus) => void` | – |  |
| `onError` | `(error: unknown) => void` | – | Called with the rejection reason. |
| `resetAfter` | `number \| { success?: number; error?: number }` | `{ success: 2000, error: 4000 }` | Milliseconds before returning to idle. |
| `loadingLabel` | `ReactNode` | – | Shown next to the spinner. Hidden on icon sizes. |
| `successLabel` | `ReactNode` | `"Done"` |  |
| `errorLabel` | `ReactNode \| (error: unknown) => ReactNode` | `"Failed"` |  |
| `disabled` | `boolean` | `false` |  |
| `focusableWhenDisabled` | `boolean` | `false` | Always true while loading. |
| `nativeButton` | `boolean` | `true` | Set to false when render is not a <button>. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="button"` | Target buttons in CSS. |
| `data-status` | idle, loading, success or error. Present once feedback, loading or status is used. |
| `data-disabled` | Present when the button is disabled. |
| `aria-busy` | Present while loading. |

### useButtonFeedback

Runs the same feedback flow from anywhere, such as a form’s `onSubmit`. Accepts `resetAfter`, `onStatusChange` and `onError`. See the [useButtonFeedback guide](https://hextaui.com/docs/use-button-feedback) for the full timing.

| Returns | Description |
| --- | --- |
| `track(action)` | Pass a promise or a function returning one. Calls while a request is in flight are ignored. |
| `buttonProps` | Spread on <Button> to show the status and pause the reset on hover and focus. |
| `status` | The current ButtonStatus. |
| `error` | The last rejection reason. |
| `reset()` | Cancels the request and returns to idle. |
| `isPending()` | Whether a request is in flight. |

---

# Button group

> Buttons joined into one control, with shared seams, separators, text addons, nesting and vertical stacks.

Docs: https://hextaui.com/docs/button-group
Markdown: https://hextaui.com/docs/button-group.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/button-group.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/button-group.tsx`, `components/ui/separator.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from "@/components/ui/button-group"
```

```tsx
<ButtonGroup aria-label="Text formatting">
  <Button variant="outline">Bold</Button>
  <Button variant="outline">Italic</Button>
  <Button variant="outline">Underline</Button>
</ButtonGroup>
```

Button group joins the buttons you already use. Install `<Button />` as well.

## Composition

```text
ButtonGroup
├── Button
├── ButtonGroupSeparator
├── ButtonGroupText
└── ButtonGroup
```

## Examples

### Sizes

Set `size` on each button. Joined corners stay square at every size, and the outer corners keep the button’s radius.

### Split button

Filled buttons sit flush, so add a `<ButtonGroupSeparator />` between them. A dropdown trigger can be any segment.

### Separators

Separators between icon buttons, with a toggle that reports its pressed state.

### Feedback inside a group

When a button’s label changes width during loading, success or error, the segments after it slide along instead of jumping.

### Vertical

`orientation="vertical"` stacks the segments. Separators turn horizontal automatically.

### Nested groups

Groups inside a group become separate clusters with a gap between them, each joined on its own.

### With text and an input

`<ButtonGroupText />` adds a label or prefix. Render it as a `<label>` to name the input. The input stretches to fill the row.

### Disabled and invalid

Disable or mark a single segment with `aria-invalid`. An invalid segment rises above its neighbours so its red ring is never covered.

### Full width

Give the group a width and each button `flex-1` to split the space evenly.

### As a fieldset

Use `render` to output a `<fieldset>` inside forms.

### Right to left

Joined corners, separators and nested clusters mirror in right-to-left layouts.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves through the segments in order. The focused segment rises so its ring and border are never covered. |
| `Enter` `Space` | Activates the focused button. |

## Accessibility

- The group has `role="group"`. Give it an `aria-label` that describes the set, like “Message actions”.
- Icon-only segments need their own `aria-label`.
- Separators are exposed as separators with the right orientation. Add `decorative` when the line is only visual.

## API reference

Every part renders a `<div>` and accepts its attributes.

### ButtonGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="button-group"` | Target groups in CSS. |
| `data-orientation` | The current orientation. |

### ButtonGroupSeparator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | – | Defaults to the opposite of the group’s orientation. |
| `decorative` | `boolean` | `false` | Hide the line from screen readers. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="button-group-separator"` | Target separators in CSS. |
| `data-orientation` | The resolved orientation. |

### ButtonGroupText

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` | Render a <label> to name an input in the group. |

| Attribute | Description |
| --- | --- |
| `data-slot="button-group-text"` | Target text segments in CSS. |

---

# Calendar

> A date grid for single, range and multiple selection, with sliding months, range previews and touch-sized days.

Docs: https://hextaui.com/docs/calendar
Markdown: https://hextaui.com/docs/calendar.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/calendar.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add react-day-picker @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/calendar.tsx`, `components/ui/button.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Calendar } from "@/components/ui/calendar"
```

```tsx
const [date, setDate] = React.useState<Date>()

<Calendar mode="single" selected={date} onSelect={setDate} />
```

Calendar wraps react-day-picker’s `<DayPicker />`, so every DayPicker prop works as documented on daypicker.dev. HextaUI adds styling, month transitions, a range preview and a hydration-safe today.

## Examples

### Range

With `mode="range"`, after the first click hovering or focusing a day previews the range the next click will select. `numberOfMonths` shows months side by side, stacked on narrow screens.

### Range limits

`min` and `max` limit the range length in days. With `excludeDisabled`, a range that would include a disabled day starts over instead.

### Multiple

`mode="multiple"` toggles individual days. `max` caps how many can be selected.

### Month and year dropdowns

`captionLayout="dropdown"` replaces the caption with native selects, so phones get their own picker. Set `startMonth` and `endMonth` to bound the years.

### Bounded

Navigation stops at `startMonth` and `endMonth`, and `disabled` blocks days outside the window. `useToday()` gives a today that is safe to use during server rendering.

### Controlled month

Pass `month` and `onMonthChange` to drive the visible month. Jumps slide in the direction of travel and the height eases between 5 and 6 week rows.

### Week numbers

`showWeekNumber` adds a week column. `ISOWeek` uses ISO numbering, starting on Monday. `showOutsideDays={false}` hides days of other months.

### Fixed today

Pass `today` to pin the highlighted day, for tests or another time zone. `animate={false}` turns off month transitions.

### Inside a sheet

Inside a sheet, popover or dialog the calendar drops its own background and blends with the surface.

### Right to left

Pass a `locale` from `react-day-picker/locale` and `dir="rtl"`. Arrows, navigation and the slide direction all mirror. Inside a `dir="rtl"` DirectionProvider, the direction is picked up automatically.

## Keyboard

Focus a day, then use these keys. Moving past the visible month changes the month.

| Key | Action |
| --- | --- |
| `←` `→` | Previous or next day. Reversed in right-to-left layouts. |
| `↑` `↓` | Same day of the previous or next week. |
| `Shift` `←` `→` | Previous or next month. |
| `Shift` `↑` `↓` | Previous or next year. |
| `Page Up` `Page Down` | Previous or next month. |
| `Shift` `Page Up` `Page Down` | Previous or next year. |
| `Home` | First day of the week. |
| `End` | Last day of the week. |
| `Enter` `Space` | Selects the focused day. |

## Accessibility

- The month is a grid. Each day is a button with a full date label, and selected days set `aria-selected`.
- Month changes made with the keyboard skip the slide and only fade, so focus never moves under a moving grid.
- With reduced motion, month changes fade and the height change is instant.
- On touch screens the day cells grow to 44px.

## API reference

Accepts every `<DayPicker />` prop. The defaults below differ from DayPicker’s or are added by HextaUI.

### Calendar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `"single" \| "multiple" \| "range"` | – | Without a mode, days are not selectable. |
| `selected` | `Date \| Date[] \| DateRange` | – | Matches the mode. |
| `onSelect` | `(selected, triggerDate, modifiers, event) => void` | – |  |
| `required` | `boolean` | – | Prevents deselecting the last selection. |
| `min` | `number` | – | Minimum days in a range, or selected in multiple mode. |
| `max` | `number` | – | Maximum days in a range, or selected in multiple mode. |
| `excludeDisabled` | `boolean` | – | Range mode. |
| `disabled` | `Matcher \| Matcher[]` | – |  |
| `month` | `Date` | – | Controlled month. |
| `defaultMonth` | `Date` | – |  |
| `onMonthChange` | `(month: Date) => void` | – |  |
| `startMonth` | `Date` | – |  |
| `endMonth` | `Date` | – |  |
| `numberOfMonths` | `number` | `1` |  |
| `captionLayout` | `"label" \| "dropdown" \| "dropdown-months" \| "dropdown-years"` | `"label"` |  |
| `navLayout` | `"around" \| "after"` | `"around"` | HextaUI default. Arrows sit on either side of the caption. |
| `showOutsideDays` | `boolean` | `true` | HextaUI default. |
| `animate` | `boolean` | `true` | Month slide and height transitions. HextaUI default. |
| `buttonVariant` | `Button variant` | `"ghost"` | Variant of the previous and next buttons. |
| `showWeekNumber` | `boolean` | `false` |  |
| `ISOWeek` | `boolean` | `false` |  |
| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | – |  |
| `fixedWeeks` | `boolean` | `false` |  |
| `today` | `Date` | – | Defaults to the client’s today, kept in sync across midnight and hydration. |
| `timeZone` | `string` | – |  |
| `locale` | `Partial<DayPickerLocale>` | – |  |
| `dir` | `"ltr" \| "rtl"` | – |  |
| `footer` | `ReactNode` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="calendar"` | Target the calendar root in CSS. |
| `--cell-size` | Day cell size. 36px, or 44px on touch screens. |
| `--cell-radius` | Corner radius of day cells and buttons. |
| `data-slot="calendar-day"` | Day cells. Carry data-selected, data-disabled, data-outside, data-today, data-hidden and data-focused. |
| `data-preview` | On day cells: start, middle or end of the hovered range preview. |
| `data-range-middle` | On day cells inside a selected range. |

### CalendarDayButton

The button inside each day. Pass your own to `components={{ DayButton }}` and reuse this one to keep the styling.

| Attribute | Description |
| --- | --- |
| `data-slot="calendar-day-button"` | Target day buttons in CSS. |
| `data-day` | The ISO date, like 2026-10-03. |
| `data-today` | Present on today, outside days excluded. |
| `data-selected-single` | Selected outside a range. |
| `data-range-start` | First day of the range. |
| `data-range-middle` | A day inside the range. |
| `data-range-end` | Last day of the range. |

### useToday

Returns today as a `Date` on the client and `undefined` during server rendering, so bounds built from it never cause a hydration mismatch. It updates at midnight. See the [useToday guide](https://hextaui.com/docs/use-today).

---

# Card

> A surface for grouping content, with three variants, edge-to-edge media, concentric radii and whole-card links.

Docs: https://hextaui.com/docs/card
Markdown: https://hextaui.com/docs/card.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/card.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/card.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardLink,
  CardTitle,
} from "@/components/ui/card"
```

```tsx
<Card>
  <CardHeader>
    <CardTitle>Team plan</CardTitle>
    <CardDescription>Billed monthly.</CardDescription>
    <CardAction>
      <Button variant="ghost" size="icon-sm" aria-label="More options">
        <IconDotsVertical />
      </Button>
    </CardAction>
  </CardHeader>
  <CardContent>12 of 20 seats used.</CardContent>
  <CardFooter>
    <Button>Manage seats</Button>
  </CardFooter>
</Card>
```

## Composition

```text
Card
├── CardHeader
│   ├── CardTitle
│   │   └── CardLink
│   ├── CardDescription
│   └── CardAction
├── CardContent
└── CardFooter
```

## Examples

### Variants

`default` sits on a hairline ring with a soft shadow, `outline` drops the fill and shadow, and `muted` uses a filled surface for quieter sections.

### Sizes

`size="sm"` tightens the spacing, radius and title size together, so a compact card still looks like part of the same family.

### Media

An image, video, picture or aspect ratio placed first or last runs edge to edge. The card drops the padding on that side and clips the media to its corners.

### Clickable card

Put a `<CardLink />` in the title to make the whole card one link. Buttons and other controls inside stay clickable and keep their own focus, like the star here.

### Clickable variants

Each variant gets its own hover feedback once it holds a link, and the focus ring wraps the whole card when the link is focused with the keyboard.

### Borders

Add `border-b` to the header or `border-t` to the footer and the card adds matching padding on the inner side.

### Nested

A card inside CardContent derives its radius from the parent’s radius minus the spacing, so the corners stay concentric.

### Long content

Unbroken titles, long URLs, emoji and CJK text wrap inside a narrow card instead of pushing it wider.

### Semantics

Every part takes a `render` prop, so a card can be an `<article>` with a real heading, header and footer.

### Right to left

The action moves to the inline start and the footer follows the reading direction.

## Keyboard

A card is not focusable on its own. These keys apply when it holds a `<CardLink />`.

| Key | Action |
| --- | --- |
| `Tab` | Focuses the card link, which draws the focus ring around the whole card, then moves on to each control inside it. |
| `Enter` | Follows the card link. |

## Accessibility

- The link’s accessible name is its own text, so keep `<CardLink />` inside the title rather than wrapping the whole card in an anchor.
- Controls inside a clickable card are lifted above the link’s hit area, so they stay reachable by pointer and keyboard.
- Use `render` on `<CardTitle />` to give the title the heading level that fits your page.

## API reference

Every part renders a `<div>` by default, accepts its attributes and takes a `render` prop to swap the element.

### Card

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "muted"` | `"default"` |  |
| `size` | `"default" \| "sm"` | `"default"` | Scales spacing, radius and title size together. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card"` | Target the card in CSS. |
| `data-variant` | The current variant. |
| `data-size` | The current size. |
| `data-link` | Present while the card contains a CardLink. |
| `--card-spacing` | Inner spacing shared by every part. Set by the size. |
| `--card-radius` | Corner radius. Nested cards derive theirs from the parent. |
| `--card-title-size` | Font size used by CardTitle. |

### CardHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card-header"` | A grid that places CardAction in the top end corner. |

### CardTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card-title"` | Target the title. |

### CardDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card-description"` | Target the description. |

### CardAction

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card-action"` | Spans the title and description rows, above a CardLink’s hit area. |

### CardContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card-content"` | Passes the card radius and spacing down to nested cards. |

### CardFooter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="card-footer"` | Target the footer. |

### CardLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<a>` | Pass your router’s link component here. |

| Attribute | Description |
| --- | --- |
| `data-slot="card-link"` | Stretches its hit area over the whole card. |

---

# Carousel

> Native scroll-snap slides with momentum on touch, mouse dragging, arrow keys, dots, thumbnails and an autoplay that pauses when it should.

Docs: https://hextaui.com/docs/carousel
Markdown: https://hextaui.com/docs/carousel.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/carousel.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/carousel.tsx`, `components/ui/button.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Carousel,
  CarouselContent,
  CarouselDots,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"
```

```tsx
<Carousel aria-label="Featured">
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
  <CarouselDots />
</Carousel>
```

Slides scroll natively with CSS scroll snap, so touch momentum and trackpad scrolling feel like the platform. A mouse can drag, and the arrow keys move one slide at a time.

## Composition

```text
Carousel
├── CarouselContent
│   └── CarouselItem
├── CarouselPrevious
├── CarouselNext
├── CarouselDots
├── CarouselCounter
├── CarouselAutoplayToggle
└── CarouselThumbnails
    └── CarouselThumbnail
```

## Examples

### API

Pass `setApi` to get the carousel API, then listen for `select` to show your own position. Next is disabled on the last slide but keeps focus.

### Several per view

Items set their own `basis`. Gutters come from the `spacing` prop, so they stay exact at any basis.

### Dots and counter

The active dot stretches as the slides scroll and its neighbours make room. The counter only spins the digit that changed.

### Autoplay

`autoplay` is off by default and stays off with reduced motion. It pauses on hover, keyboard focus, touch, drag, a hidden tab, or when scrolled out of view, and the active dot fills as the timer runs.

### Thumbnails

`<CarouselThumbnails />` follows the main carousel and scrolls to keep the active thumbnail in view.

### Vertical

`orientation="vertical"` needs a height on `<CarouselContent />`. The buttons move above and below.

### Controlled

Pass `index` and `onIndexChange`. Swiping updates your state and your state scrolls the carousel.

### Rewind and start index

`rewind` sends Next on the last slide back to the first. `defaultIndex` opens on a slide without a scroll animation.

### Links and focusable content

Dragging a link with the mouse scrolls without opening it. Tabbing to a slide that is off screen scrolls it into view.

### Adding and removing slides

Dots, the counter and the buttons update as slides come and go.

### Nested

Arrow keys, dragging and dots only move the carousel you are in.

### Long content and a single slide

Unbroken text wraps inside its slide. With one slide the dots hide and the buttons stay disabled.

### Right to left

Slides start on the right, the arrows flip, the Left arrow key moves forward and the dots fill from the right.

## Keyboard

Keys work while focus is anywhere inside the carousel, except in text fields and nested carousels.

| Key | Action |
| --- | --- |
| `→` | Next slide. Previous in right-to-left layouts. ↓ in vertical carousels. |
| `←` | Previous slide. Next in right-to-left layouts. ↑ in vertical carousels. |
| `Tab` | Moves through the buttons, the active dot and the slides’ content, scrolling off-screen slides into view. |
| `Enter` `Space` | Activates the focused button, dot or thumbnail. |

## Accessibility

- The root is a `region` described as a carousel. Give it an `aria-label`.
- Each item is a `group` described as a slide and labelled with its position, like “3 of 5”.
- A polite live region announces the new slide after keyboard or button navigation, and stays quiet while autoplay runs.
- Dots and thumbnails use a single tab stop, and focus follows the active one.
- Previous and Next stay focusable when disabled, so focus is never lost at either end.

## API reference

### Carousel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `spacing` | `"none" \| "sm" \| "default" \| "lg"` | `"default"` | Gap between slides. |
| `index` | `number` | – |  |
| `defaultIndex` | `number` | `0` |  |
| `onIndexChange` | `(index: number) => void` | – |  |
| `rewind` | `boolean` | `false` | Wrap from the last slide back to the first. |
| `mouseDrag` | `boolean` | `true` | Let a mouse drag the slides. |
| `autoplay` | `boolean \| { delay?: number }` | `false` | Advance on a timer. delay defaults to 5000ms, minimum 1000ms. |
| `setApi` | `(api: CarouselApi) => void` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel"` | Target the root in CSS. |
| `data-orientation` | The orientation. |
| `--carousel-spacing` | The gap between slides, set by spacing. |

### CarouselContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | – | Applied to the track that holds the slides. |
| `viewportClassName` | `string` | – | Applied to the scrolling viewport. |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-content"` | The scrolling viewport. |
| `data-slot="carousel-container"` | The track inside it. |
| `data-scrollable` | Present when there is more than one position. |
| `data-dragging` | Present while a mouse drag is in progress. |

### CarouselItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-item"` | Set basis-* to show several per view. |

### CarouselPrevious and CarouselNext

Both render a `<Button />` and accept its props. They sit outside the content, so leave room around the carousel.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ButtonProps["variant"]` | `"outline"` |  |
| `size` | `ButtonProps["size"]` | `"icon-sm"` |  |
| `children` | `ReactNode` | `Arrow icon` | Follows the orientation and direction. |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-previous"` | Labelled “Previous slide”. |
| `data-slot="carousel-next"` | Labelled “Next slide”. |
| `data-disabled` | Present at either end. The button stays focusable. |

### CarouselDots

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Choose slide"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-dots"` | The group of dots. Hidden with one position. |
| `data-slot="carousel-dot"` | Each dot. The active one has aria-current. |
| `--dot-active` | 0 to 1, how active a dot is while scrolling. |

### CarouselCounter

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-counter"` | Shows the current position over the total with a rolling digit. |

### CarouselAutoplayToggle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `ButtonProps["variant"]` | `"ghost"` |  |
| `size` | `ButtonProps["size"]` | `"icon-sm"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-autoplay-toggle"` | Labelled “Pause slideshow” or “Play slideshow”. |

### CarouselThumbnails

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Slides"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-thumbnails"` | The scrolling strip. |

### CarouselThumbnail

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `index` | `number` | – | The slide it opens. Defaults to its position in the strip. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="carousel-thumbnail"` | Target thumbnails in CSS. |
| `data-active` | Present while its slide is in view. |

### CarouselApi

Returned through `setApi` and `useCarousel()`. Pass `jump: true` to move without animating.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scrollPrev` | `(jump?: boolean) => void` | – |  |
| `scrollNext` | `(jump?: boolean) => void` | – |  |
| `scrollTo` | `(index: number, jump?: boolean) => void` | – | Scrolls to a snap position. |
| `scrollToSlide` | `(slideIndex: number, jump?: boolean) => void` | – | Scrolls to the position that shows a slide. |
| `canScrollPrev` | `() => boolean` | – |  |
| `canScrollNext` | `() => boolean` | – |  |
| `selectedScrollSnap` | `() => number` | – |  |
| `scrollSnapList` | `() => number[]` | – |  |
| `slidesInView` | `() => number[]` | – |  |
| `slideNodes` | `() => HTMLElement[]` | – |  |
| `viewportNode` | `() => HTMLElement \| null` | – |  |
| `play` | `() => void` | – |  |
| `stop` | `() => void` | – |  |
| `isPlaying` | `() => boolean` | – |  |
| `on / off` | `(event: "select" \| "scroll" \| "settle" \| "reInit", listener) => CarouselApi` | – |  |

### useCarousel

Use inside `<Carousel />` to build your own controls. Returns `api`, `orientation`, `selectedIndex`, `snapCount`, `slideCount`, `slidesInView`, `canScrollPrev`, `canScrollNext`, `isPlaying` and the scroll and play methods.

---

# Chart

> Recharts charts with themed colors, a tooltip and legend that read labels from one config, and keyboard navigation with a visible focus ring.

Docs: https://hextaui.com/docs/chart
Markdown: https://hextaui.com/docs/chart.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/chart.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add recharts cn
```

Copy `components/ui/chart.tsx` into your project. Their source is in this page's Markdown.

## Usage

You build charts with Recharts components and add the parts from `chart` only where you need them. Recharts is not wrapped, so its own docs and upgrade guides apply as they are.

```tsx
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts"

import {
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig,
} from "@/components/ui/chart"
```

A `ChartConfig` maps each data key to a label, an optional icon and a color. It stays separate from the data, so one config can serve several charts.

```tsx
const chartConfig = {
  desktop: {
    label: "Desktop",
    color: "var(--chart-1)",
  },
  mobile: {
    label: "Mobile",
    color: "var(--chart-2)",
  },
} satisfies ChartConfig
```

```tsx
<ChartContainer
  aria-label="Bar chart of desktop and mobile visitors by month"
  config={chartConfig}
  className="min-h-52 w-full"
>
  <BarChart data={chartData}>
    <CartesianGrid vertical={false} />
    <XAxis dataKey="month" tickLine={false} axisLine={false} />
    <ChartTooltip content={<ChartTooltipContent />} />
    <ChartLegend content={<ChartLegendContent />} />
    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
  </BarChart>
</ChartContainer>
```

Give `<ChartContainer />` a height, a `min-h-*` or an `aspect-*` so the chart can measure itself on the first render. Without one it falls back to `aspect-video`.

## Composition

```text
ChartContainer
└── BarChart / LineChart / AreaChart / …
    ├── ChartTooltip
    │   └── ChartTooltipContent
    └── ChartLegend
        └── ChartLegendContent
```

## Theming

Each config key becomes a `--color-KEY` variable scoped to its chart. Point it at a theme token, at any CSS color, or give it separate `light` and `dark` values.

```tsx
const chartConfig = {
  desktop: {
    label: "Desktop",
    icon: IconDeviceDesktop,
    color: "var(--chart-1)",
  },
  mobile: {
    label: "Mobile",
    theme: {
      light: "oklch(0.5 0.17 285)",
      dark: "oklch(0.75 0.14 190)",
    },
  },
} satisfies ChartConfig
```

Use the variable wherever Recharts takes a color: on components, in your data, or in Tailwind classes.

```tsx
<Bar dataKey="desktop" fill="var(--color-desktop)" />

const chartData = [
  { browser: "chrome", visitors: 275, fill: "var(--color-chrome)" },
]

<LabelList className="fill-(--color-desktop)" />
```

The theme ships five chart tokens, `--chart-1` to `--chart-5`: blue, teal, amber, violet and rose. In this order, neighbouring colors stay distinct with the common forms of color blindness, and each one has at least 3:1 contrast against the light and dark backgrounds. Use them in order and keep the legend or labels on, so color is never the only cue.

Keys that are not valid in a CSS name, such as `Mobile users`, become `--color-Mobile-users`.

## Examples

### Bar chart

A grid, an axis, `<ChartTooltip />` and `<ChartLegend />`. The tooltip and legend read their labels and colors from the config.

### Line chart

`indicator="line"` matches the tooltip keys to the lines they describe.

### Stacked bars

Bars with the same `stackId` stack. Round only the outer ends, so the stack reads as one bar.

### Horizontal bars

Set `layout="vertical"` on the chart and swap the axis types. `<LabelList />` prints each value at the end of its bar.

### Donut

Each slice takes its color from `fill` in the data. `nameKey` on the tooltip and legend looks up the label for each slice in the config.

### Radar

Polar grids and axes pick up the same muted strokes and labels as cartesian ones.

### Tooltip

Switch between `dot`, `line` and `dashed` indicators, and hide the label with `hideLabel`. `defaultIndex` on `<ChartTooltip />` shows a point on the first render.

### Formatting values

`valueFormatter` formats the number and keeps the indicator and name. `labelFormatter` does the same for the label. To replace a whole row instead, use `formatter`.

### Icons

An `icon` in the config replaces the color key in the tooltip and legend.

### Light and dark colors

A `theme` object picks a different color in each theme. Switch the site theme to see it change.

### Negative values

Color each bar with `<Cell />` and mark zero with `<ReferenceLine />`.

### Long labels

Long series names wrap in the legend and the tooltip, and large values stay on one line beside them.

### Right to left

Recharts does not mirror axes on its own. Set `reversed` on the x-axis and move the y-axis to the right. Pass `locale` to the tooltip to show the reader's digits.

## Keyboard

Recharts turns on `accessibilityLayer` by default, so the chart is one tab stop that you move through point by point.

| Key | Action |
| --- | --- |
| `Tab` | Focuses the chart and shows a focus ring. |
| `←` `→` | Moves the tooltip to the next or previous point. In a reversed axis the keys follow the screen. |
| `Enter` | Shows or hides the tooltip at the current point. |

## Accessibility

- Charts are images to screen readers. Name each one with a visible title nearby or an `aria-label` on the Recharts chart, and offer a table when people need the exact values.
- The tooltip and legend name every series in text, so a reader never has to match colors alone.
- With reduced motion, Recharts skips its enter animations and the tooltip jumps between points instead of gliding.
- Tooltip values are formatted in `en-US` unless you pass `locale`, so the server and browser render the same text.

## API reference

The parts sit on top of Recharts. Every Recharts prop still works on the chart components you put inside.

### ChartContainer

Provides the config, writes the color variables and renders a Recharts `<ResponsiveContainer />` around its child. Takes every `<div>` prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `config` | `ChartConfig` | – | Labels, icons and colors for each data key. |
| `children` | `ReactElement` | – | One Recharts chart, such as <BarChart />. |
| `initialDimension` | `{ width: number; height: number }` | `{ width: 320, height: 200 }` | The size used before the container is measured. |
| `id` | `string` | – | Names the chart in data-chart. Generated when omitted. |

| Attribute | Description |
| --- | --- |
| `data-slot="chart"` | The container. |
| `data-chart` | The id the color variables are scoped to. |
| `--color-KEY` | One color variable per configured key. |

### ChartConfig

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | – |  |
| `icon` | `ComponentType` | – | Replaces the color key in the tooltip and legend. |
| `color` | `string` | – | Any CSS color or variable. |
| `theme` | `{ light: string; dark: string }` | – | Use instead of color for a color per theme. |

### ChartTooltip

The Recharts `<Tooltip />`, with a shorter glide between points. Takes every Recharts tooltip prop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `ReactElement \| (props) => ReactNode` | – | Usually <ChartTooltipContent />. |
| `animationDuration` | `number` | `200` |  |
| `animationEasing` | `string` | `"ease-out"` |  |
| `defaultIndex` | `number` | – | Shows the tooltip at this point on first render. |

### ChartTooltipContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indicator` | `"dot" \| "line" \| "dashed"` | `"dot"` |  |
| `hideLabel` | `boolean` | `false` |  |
| `hideIndicator` | `boolean` | `false` |  |
| `labelKey` | `string` | – | The config or data key to use for the label. |
| `nameKey` | `string` | – | The config or data key to use for each name. |
| `valueFormatter` | `(value, name, item) => ReactNode` | – | Formats each value and keeps the indicator and name. |
| `labelFormatter` | `(label, payload) => ReactNode` | – |  |
| `formatter` | `(value, name, item, index, payload) => ReactNode` | – | Replaces each row. |
| `locale` | `Intl.LocalesArgument` | `"en-US"` | Formats numeric values. |
| `color` | `string` | – | One indicator color for every row. |
| `className` | `string` | – |  |
| `labelClassName` | `string` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="chart-tooltip"` | The box. |
| `data-slot="chart-tooltip-label"` | The label. |
| `data-slot="chart-tooltip-item"` | One row per series. |
| `data-slot="chart-tooltip-indicator"` | The color key. |
| `data-indicator` | On the key: dot, line or dashed. |
| `--chart-indicator` | The key's color. |

### ChartLegend

The Recharts `<Legend />`. Takes every Recharts legend prop, and lists series in the order you declare them instead of alphabetically.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `ReactElement \| (props) => ReactNode` | – | Usually <ChartLegendContent />. |
| `itemSorter` | `"value" \| "dataKey" \| (item) => number \| string \| null` | `null` | null keeps the declared order. |

### ChartLegendContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hideIcon` | `boolean` | `false` |  |
| `nameKey` | `string` | – | The config or data key to use for each name. |
| `className` | `string` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="chart-legend"` | The list. |
| `data-slot="chart-legend-item"` | One entry per series. |
| `data-slot="chart-legend-indicator"` | The color swatch. |

### useChart

Returns `{ config }` inside a `<ChartContainer />`, for building your own tooltip or legend content.

---

# Checkbox

> A checkbox whose check draws in, with indeterminate parents, groups and labels that share its hover.

Docs: https://hextaui.com/docs/checkbox
Markdown: https://hextaui.com/docs/checkbox.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/checkbox.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react cn
```

Copy `components/ui/checkbox.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"
```

```tsx
<label className="flex items-center gap-3">
  <Checkbox defaultChecked />
  Remember this device
</label>
```

## Composition

```text
CheckboxGroup
└── Checkbox
```

## Examples

### States

`disabled`, `readOnly`, `indeterminate` and `aria-invalid`. A read-only box keeps its value and stays focusable, but ignores clicks and keys.

### Select all

Inside a `<CheckboxGroup />`, a checkbox with `parent` ticks every value in `allValues`. It turns indeterminate when only some are ticked.

### Nested groups

Groups nest. Each parent reflects the state of the group directly below it, and the top parent covers everything.

### Controlled

Pass `checked` and `onCheckedChange` to keep the state in your own code.

### Form

A hidden input submits `name` and `value` like a native checkbox, and `required` blocks submit until it is ticked.

### Sibling label

When the label can’t wrap the box, render the checkbox as a `<button>` with `nativeButton` and point the label at it with `htmlFor`.

### Cards

Wrap a whole card in the label so the card is the hit area, and style it with `has-data-checked`.

### Long content

The box stays on the first line while a long label and unbroken text wrap beside it.

### Right to left

The box sits on the inline start side and the label follows the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Space` | Ticks or unticks the checkbox. |
| `Enter` | Submits the form the checkbox belongs to, like a native checkbox. It never toggles the box. |
| `Tab` | Moves focus to the next checkbox. |

## Accessibility

- Wrap the checkbox and its text in a `<label>`. The label names the checkbox, and hovering or pressing it gives the box the same feedback as hovering the box itself.
- Give every `<CheckboxGroup />` an `aria-label` or `aria-labelledby` so screen readers announce what the group is for.
- The hit area extends past the 16px box, and grows on touch screens.
- The check draws in when ticked. With reduced motion it appears without the stroke animation.

## API reference

Built on the Base UI checkbox and checkbox group. Both accept the props of the primitive they wrap.

### Checkbox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – |  |
| `defaultChecked` | `boolean` | `false` |  |
| `onCheckedChange` | `(checked: boolean, details) => void` | – |  |
| `indeterminate` | `boolean` | `false` | Shows a dash: neither ticked nor unticked. |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` | Focusable, but the value can’t change. |
| `required` | `boolean` | `false` |  |
| `name` | `string` | – | Submitted with the form when ticked. |
| `value` | `string` | – | Identifies the box inside a group and is what the form submits. Falls back to name, then “on”. |
| `uncheckedValue` | `string` | – | Submitted when unticked. Nothing by default. |
| `parent` | `boolean` | `false` | Controls every value in the group’s allValues. Only inside a CheckboxGroup. |
| `inputRef` | `Ref<HTMLInputElement>` | – |  |
| `nativeButton` | `boolean` | `false` | Set to true when render is a <button>. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="checkbox"` | Target the box in CSS. |
| `data-checked` | Present when ticked. |
| `data-unchecked` | Present when unticked. |
| `data-indeterminate` | Present when indeterminate. |
| `data-disabled` | Present when disabled. |
| `data-readonly` | Present when read-only. |
| `data-required` | Present when required. |
| `data-invalid` | Present when invalid inside a Base UI Field. |

### CheckboxGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` | – | Values of the ticked checkboxes. |
| `defaultValue` | `string[]` | – |  |
| `onValueChange` | `(value: string[], details) => void` | – |  |
| `allValues` | `string[]` | – | Every value in the group. Required for a parent checkbox. |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="checkbox-group"` | Target the group in CSS. |
| `data-disabled` | Present when the group is disabled. |

---

# Collapsible

> A panel that shows and hides with height motion you can reverse mid-way, without jumping the layout.

Docs: https://hextaui.com/docs/collapsible
Markdown: https://hextaui.com/docs/collapsible.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/collapsible.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react cn
```

Copy `components/ui/collapsible.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
  CollapsibleTriggerIcon,
} from "@/components/ui/collapsible"
```

```tsx
<Collapsible>
  <CollapsibleTrigger render={<Button variant="outline" />}>
    Details
    <CollapsibleTriggerIcon data-icon="inline-end" />
  </CollapsibleTrigger>
  <CollapsibleContent>
    Shipping takes 2 business days.
  </CollapsibleContent>
</Collapsible>
```

## Composition

```text
Collapsible
├── CollapsibleTrigger
│   └── CollapsibleTriggerIcon
└── CollapsibleContent
```

## Examples

### Open by default

`defaultOpen` starts the panel open without taking over its state.

### Show more

The panel sits above its trigger. When it closes, the gap in the parent’s flex layout collapses in the same animation, so the button below never jumps.

### Controlled

Pass `open` and `onOpenChange` to drive the panel from your own state. Toggling mid-animation reverses from where the panel is.

### Disabled

`disabled` on the root keeps the panel in its current state and makes the trigger ignore clicks and keys.

### Custom icon

Children of `<CollapsibleTriggerIcon />` replace the chevron. Style the open state with `group-data-panel-open/collapsible-trigger`.

### File tree

Each folder is its own collapsible. Outer panels grow smoothly as inner ones open.

### Inside a card

Closed panels stay in the page with hidden=“until-found”, so Cmd/Ctrl+F for “webhook” opens this one.

### Unmounted when closed

Set `hiddenUntilFound={false}` on the content to remove it from the DOM while closed, for heavy panels you don’t want rendered up front.

### Long content

Unbroken strings wrap inside the panel instead of widening the page.

### Right to left

Chevrons mirror and nested indents follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | Opens or closes the panel from the trigger. |
| `Tab` | Moves focus from the trigger into the open panel. Closed panels are skipped. |

## Accessibility

- The trigger gets `aria-expanded` and `aria-controls` automatically.
- Icon-only triggers need an `aria-label`. `<CollapsibleTriggerIcon />` is hidden from assistive tech.
- With reduced motion the panel opens and closes without animating its height.

## API reference

Built on the Base UI collapsible. Every part accepts the props of the primitive it wraps.

### Collapsible

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="collapsible"` | Target the root in CSS. |
| `data-open` | Present when open. |
| `data-closed` | Present when closed. |

### CollapsibleTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` | Usually a Button. |

| Attribute | Description |
| --- | --- |
| `data-slot="collapsible-trigger"` | Target the trigger in CSS. |
| `data-panel-open` | Present when the panel is open. Style children with group-data-panel-open/collapsible-trigger. |

### CollapsibleTriggerIcon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `<IconChevronDown />` | The default chevron flips when the panel opens. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="collapsible-trigger-icon"` | Hidden from assistive tech. Nudges down while the trigger is pressed. |

### CollapsibleContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | – | Applied to the inner wrapper, so padding never fights the height animation. |
| `hiddenUntilFound` | `boolean` | `true` | Keeps the closed panel in the DOM so page search can find and open it. |
| `keepMounted` | `boolean` | `false` | Ignored while hiddenUntilFound is on. |

| Attribute | Description |
| --- | --- |
| `data-slot="collapsible-content"` | Target the panel in CSS. |
| `data-open` | Present when open. |
| `data-closed` | Present when closed. |
| `data-starting-style` | Present while the panel animates in. |
| `data-ending-style` | Present while the panel animates out. |
| `--collapsible-panel-height` | The panel’s measured height. |
| `--collapsible-panel-width` | The panel’s measured width. |
| `--collapsible-gap-start` | The parent’s gap before the panel, collapsed while closed. |
| `--collapsible-gap-end` | The parent’s gap after the panel, collapsed while closed. |

---

# Combobox

> A filterable select with chips, groups and async results, in a popup that resizes as you type.

Docs: https://hextaui.com/docs/combobox
Markdown: https://hextaui.com/docs/combobox.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/combobox.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/combobox.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
```

```tsx
const fruits = ["Apple", "Banana", "Cherry"]

<Combobox items={fruits}>
  <ComboboxInput placeholder="Select a fruit" />
  <ComboboxContent>
    <ComboboxEmpty>No fruit found.</ComboboxEmpty>
    <ComboboxList>
      {(item: string) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

Pass the options to `items` and render each one with a function inside `<ComboboxList />`. The combobox filters them as you type and only renders the matches. Objects work too: their `label` is shown in the input and their `value` is submitted.

## Composition

### Input

Type in the field to filter the list.

```text
Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    ├── ComboboxStatus
    └── ComboboxList
        ├── ComboboxItem
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxCollection
        │       └── ComboboxItem
        └── ComboboxSeparator
```

### Button trigger

A button shows the value and the search field moves into the popup.

```text
Combobox
├── ComboboxTrigger
│   └── ComboboxValue
└── ComboboxContent
    ├── ComboboxInput
    ├── ComboboxEmpty
    └── ComboboxList
        └── ComboboxItem
```

### Chips

With `multiple`, each selected item becomes a chip before the input.

```text
Combobox
├── ComboboxChips
│   └── ComboboxValue
│       ├── ComboboxChip
│       └── ComboboxChipsInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        └── ComboboxItem
```

## Examples

### Clear button

`showClear` adds a clear button that takes the chevron’s place while there is a value, so the field never grows.

### With icons

Icons inside an item are sized and muted for you. `autoHighlight` highlights the first match while typing, so `Enter` picks it.

### Groups and separators

Pass groups shaped like `{ value, items }` and render each with `<ComboboxGroup />`, `<ComboboxLabel />` and `<ComboboxCollection />`. Empty groups hide while filtering.

### Multiple

With `multiple`, selections become chips inside `<ComboboxChips />`. The popup stays open while you pick, Backspace in the empty input removes the last chip, and the arrow keys move between chips.

### Search inside the popup

Use `<ComboboxTrigger />` for a select-like field. Put the input inside `<ComboboxContent />` and it becomes a search box with an icon, and the popup widens to at least 15rem.

### Trigger rendered as a Button

Pass `render` to the trigger to use any button. The popup anchors to it and keeps at least its width.

### Controlled

Control the selection with `value` and `onValueChange`, and the popup with `open` and `onOpenChange`. Clearing sets the value to `null`.

### Disabled, invalid and disabled items

`disabled` on the root dims the field and its buttons. `aria-invalid` on the input draws the error ring. Disabled items are skipped by the arrow keys.

### Long content and large lists

Long and unbroken labels wrap instead of widening the popup. `limit` caps how many matches render, which keeps a 500 item list fast.

### Async search

Turn off built-in filtering with `filter={null}`, fetch on `onInputValueChange`, and show progress in `<ComboboxStatus />`, which announces it to screen readers. The popup height animates as results change.

### Inside a sheet

The popup layers above the sheet, and Escape closes the popup before the sheet.

### Right to left

The popup picks up the field’s direction, so the clear button, chips and items mirror without extra props.

## Keyboard

| Key | Action |
| --- | --- |
| `↓` `↑` | Opens the popup and moves the highlight through the matches. Disabled items are skipped. |
| `Enter` | Picks the highlighted item. With nothing highlighted it closes the popup and lets the form submit. |
| `Escape` | Closes the popup. When it is already closed, clears the value and the input. |
| `Home` `End` | Moves the text cursor to the start or end of the input. |
| `Backspace` | In an empty chips input, removes the last chip. On a focused chip, removes it. |
| `←` `→` | With chips, moves focus between chips and back to the input. Mirrored in right-to-left layouts. |
| `Tab` | Closes the popup and moves focus on. |

## Accessibility

- Give the input a visible `<label>` through `id` and `htmlFor`, or an `aria-label`. A `<ComboboxTrigger />` without visible text needs an `aria-label` too.
- The chevron button is labelled “Show options”, the clear button “Clear selection” and each chip’s remove button “Remove”.
- Highlighting moves with `aria-activedescendant`, so focus stays in the input while you browse.
- Inputs use a 16px font on touch screens so iOS doesn’t zoom in, and items grow to a 44px tap target.

## API reference

Built on the Base UI combobox. Every part accepts the props of the primitive it wraps; the tables list the ones you’ll use most.

### Combobox

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Item[] \| Group[]` | – | The options. Filtered as you type and passed to the list’s render function. |
| `multiple` | `boolean` | `false` | Select several values, shown as chips. |
| `value` | `Value \| Value[] \| null` | – |  |
| `defaultValue` | `Value \| Value[] \| null` | – |  |
| `onValueChange` | `(value, details) => void` | – |  |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `inputValue` | `string` | – |  |
| `defaultInputValue` | `string` | – |  |
| `onInputValueChange` | `(inputValue: string, details) => void` | – |  |
| `filter` | `((item, query, itemToString) => boolean) \| null` | – | Custom matching. null turns filtering off for server-side search. |
| `limit` | `number` | `-1` | Maximum number of matches to render. -1 means all. |
| `autoHighlight` | `boolean` | `false` | Highlight the first match while typing. |
| `highlightItemOnHover` | `boolean` | `true` |  |
| `openOnInputClick` | `boolean` | `true` |  |
| `loopFocus` | `boolean` | `true` | Wrap the highlight from the last item to the first. |
| `itemToStringLabel` | `(item) => string` | – | Text shown in the input for an object item. |
| `itemToStringValue` | `(item) => string` | – | Value submitted with the form for an object item. |
| `isItemEqualToValue` | `(item, value) => boolean` | – |  |
| `name` | `string` | – |  |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |
| `modal` | `boolean` | `false` | Lock page scroll and outside clicks while open. |
| `virtualized` | `boolean` | `false` | Set when rendering items with a virtualizer. |
| `locale` | `Intl.LocalesArgument` | – | Locale used for matching. |

### ComboboxInput

Outside the popup it renders the full field. Inside `<ComboboxContent />` it becomes a compact search box.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showTrigger` | `boolean` | `true outside the popup` | Show the chevron button. Always off inside the popup unless set. |
| `showClear` | `boolean` | `false` | Show a clear button in the chevron’s place while there is a value. |
| `className` | `string` | – | Applied to the input group around the input. |
| `disabled` | `boolean` | `false` |  |
| `placeholder` | `string` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-input-group"` | The field around the input. |
| `data-slot="combobox-input"` | The text input. |
| `data-slot="combobox-input-actions"` | Holds the chevron and clear buttons in one stacked cell. |
| `data-popup-open` | Present on the input while the popup is open. |
| `data-popup-side` | The side the popup opened on. |
| `data-list-empty` | Present when nothing matches. |
| `data-disabled` | Present when disabled. |
| `data-invalid` | Present when invalid inside a Base UI Field. |

### ComboboxTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | Usually a <ComboboxValue />. The chevron is added after it. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` | When set, the built-in field styles are skipped. |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-trigger"` | The trigger button. |
| `data-slot="combobox-trigger-value"` | Wraps the truncated value. |
| `data-slot="combobox-trigger-icon"` | The chevron. Flips while open. |
| `data-popup-open` | Present while the popup is open. |
| `data-placeholder` | Present while no value is selected. |

### ComboboxValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| (value) => ReactNode` | – | Render the selected value yourself, for example as chips. |
| `placeholder` | `ReactNode` | – | Shown while nothing is selected. |

### ComboboxContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"` |  |
| `align` | `"start" \| "center" \| "end"` | `"start"` |  |
| `sideOffset` | `number` | `6` |  |
| `alignOffset` | `number` | `0` |  |
| `anchor` | `Element \| RefObject<Element \| null> \| VirtualElement \| (() => Element \| VirtualElement \| null) \| null` | – | Position against another element. Defaults to the field. See useComboboxAnchor. |
| `dir` | `"ltr" \| "rtl"` | – | Defaults to the field’s direction. |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-positioner"` | Positions the popup. |
| `data-slot="combobox-content"` | The popup surface. |
| `data-slot="combobox-content-sizer"` | Measured to animate the popup’s height as matches change. |
| `data-open` | Present while open. |
| `data-side` | The side it opened on. |
| `data-align` | Its alignment. |
| `data-empty` | Present when nothing matches. |
| `data-starting-style` | Present while animating in. |
| `data-ending-style` | Present while animating out. |
| `--combobox-item-radius` | Item radius, derived from the popup radius minus its padding. |

### ComboboxList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| (item, index) => ReactNode` | – | Called for every match of items. |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-list"` | The scrolling list. |

### ComboboxItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Item` | – | The item this row represents. |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-item"` | An option. |
| `data-slot="combobox-item-indicator"` | The check, scaled in when selected. |
| `data-highlighted` | Present while highlighted. |
| `data-selected` | Present when selected. |
| `data-disabled` | Present when disabled. |

### ComboboxGroup, ComboboxLabel and ComboboxCollection

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `Item[]` | – | On ComboboxGroup: the group’s own items. |
| `children` | `(item, index) => ReactNode` | – | On ComboboxCollection: renders each match. |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-group"` | A group of items. |
| `data-slot="combobox-label"` | The group heading. |

### ComboboxEmpty, ComboboxStatus and ComboboxSeparator

`<ComboboxEmpty />` shows its children only when nothing matches. `<ComboboxStatus />` is a live region for loading and result messages. Both collapse to nothing when empty.

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-empty"` | The no-results message. |
| `data-slot="combobox-status"` | The live status message. |
| `data-slot="combobox-separator"` | A divider between groups. |

### ComboboxClear

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | `<IconX />` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-clear"` | Labelled “Clear selection”. |
| `data-visible` | Present while there is something to clear. |

### ComboboxChips

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | – | Applied to the field that wraps the chips. |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-chips"` | The field that holds chips and input. |

### ComboboxChip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showRemove` | `boolean` | `true` | Show the remove button. |

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-chip"` | A selected value. |
| `data-slot="combobox-chip-label"` | Its truncated label. |
| `data-slot="combobox-chip-remove"` | Labelled “Remove”. |

### ComboboxChipsInput

The text input that sits after the chips. Accepts the same props as the Base UI input.

| Attribute | Description |
| --- | --- |
| `data-slot="combobox-chips-input"` | The chips input. |

### Hooks and helpers

- `useComboboxAnchor()` returns a ref to pass to an element and to `anchor` on the content.
- `useComboboxFilter()` returns locale-aware `contains`, `startsWith` and `endsWith` matchers for `filter`.
- `useComboboxFilteredItems()` reads the current matches, for counts or virtualized lists.
- `createComboboxItems(data, { getValue })` builds an item collection whose selection value is a primitive id, like a database key, instead of the whole object.
- `comboboxFieldVariants` exposes the field styles for building custom fields.

---

# Command

> A searchable list of actions, inline or as a ⌘K palette, with pages, shortcuts and highlighted matches.

Docs: https://hextaui.com/docs/command
Markdown: https://hextaui.com/docs/command.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/command.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cmdk cn
```

Copy `components/ui/command.tsx`, `components/ui/button.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
} from "@/components/ui/command"
```

```tsx
<Command>
  <CommandInput placeholder="Type a command or search…" />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem onSelect={() => openCalendar()}>Calendar</CommandItem>
      <CommandItem shortcut="mod+p">Profile</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

Hotkeys use `mod` for ⌘ on Apple devices and Ctrl everywhere else. Labels are formatted per platform for you.

## Composition

```text
Command
├── CommandInput
├── CommandList
│   ├── CommandEmpty
│   ├── CommandLoading
│   ├── CommandGroup
│   │   └── CommandItem
│   │       └── CommandShortcut
│   ├── CommandSeparator
│   └── CommandPage
│       └── CommandGroup
└── CommandFooter

CommandDialog
└── Command
```

## Examples

### Basic

Typing filters and ranks items as you go. Groups with no matches disappear, and the list height animates to fit what is left.

### Dialog

Put a `<Command />` inside `<CommandDialog />` and toggle it with `useCommandHotkey`. Press ⌘K or Ctrl K. Item shortcuts run while it is open, matches are highlighted, and `preserveSearch` keeps the query and selection for the next time it opens.

### Pages

An item with `page` opens the matching `<CommandPage />`. The page title appears as a chip in the input, the list slides in from the side, and Backspace on an empty search or Escape goes back.

### Scrollable

Long lists scroll inside a capped height. The selected item is always kept in view while you move with the keyboard.

### Async results

Set `shouldFilter={false}` and render the results you fetch. `<CommandLoading />` waits 150 ms before it appears and then stays at least 300 ms, so fast responses never flash a spinner. Try both latencies.

### Long content

Headings wrap, long names truncate or wrap as you choose, and shortcuts never get pushed out.

### Right to left

Icons, shortcuts, the page chip and the page slide all follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `↓` | Selects the next item. |
| `↑` | Selects the previous item. |
| `Alt` `↓` | Jumps to the first item of the next group. |
| `Alt` `↑` | Jumps to the first item of the previous group. |
| `Home` | Selects the first item. |
| `End` | Selects the last item. |
| `Ctrl` `N` | Selects the next item. Ctrl J works too. Turn off with vimBindings. |
| `Ctrl` `P` | Selects the previous item. Ctrl K works too. Turn off with vimBindings. |
| `Enter` | Runs the selected item. On a link item, ⌘ Enter or Ctrl Enter opens it in a new tab. |
| `Esc` | Clears the search first, then goes back one page, then closes the dialog. |
| `Backspace` | Goes back one page when the search is empty. |
| `⌘` `P` | Any item shortcut runs its item while focus is inside the command menu. |

## Accessibility

- The input is a combobox that points at the selected item, so screen readers announce each item as you move.
- A polite live region announces the number of results shortly after you stop typing, and announces the page title when you open or leave a page. Change the wording with `formatResults` and `rootTitle`.
- `<CommandDialog />` has a hidden title and description, traps focus while open and returns it to the trigger when it closes.
- Item shortcuts are exposed with `aria-keyshortcuts`.
- With reduced motion on, items run without the confirm blink and pages fade instead of sliding.

## API reference

Built on `cmdk`, with `<CommandDialog />` on the Base UI dialog. Parts accept the props of the cmdk part they wrap.

### Command

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Command menu"` | Accessible name of the menu. |
| `highlight` | `boolean` | `false` | Highlights the matched letters in each item and dims the rest. |
| `shouldFilter` | `boolean` | `true` | Set to false to filter and sort the items yourself, for example when results come from a server. |
| `filter` | `(value: string, search: string, keywords?: string[]) => number` | – | Returns a score from 0 (hidden) to 1 (best match). |
| `value` | `string` | – | The selected item’s value. |
| `defaultValue` | `string` | – |  |
| `onValueChange` | `(value: string) => void` | – |  |
| `loop` | `boolean` | `false` | Wrap around at the ends of the list. |
| `vimBindings` | `boolean` | `true` | Ctrl N, J, P and K navigation. |
| `disablePointerSelection` | `boolean` | `false` |  |
| `formatResults` | `(count: number) => string` | `"3 results"` | Text announced to screen readers after typing. |
| `rootTitle` | `string` | `"All commands"` | Announced when you leave the last page and return to the root. |

| Attribute | Description |
| --- | --- |
| `data-slot="command"` | Target the root in CSS. |
| `data-highlighting` | Present while highlight is on and the search is not empty. |
| `--command-radius` | Outer radius. Items derive a concentric radius from it. |
| `--command-inset` | Padding between the list edge and its items. |

### CommandDialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `preserveSearch` | `boolean` | `false` | Keep the dialog mounted so the query, page and selection survive closing. The query is selected when it reopens. |
| `title` | `string` | `"Command menu"` | Visually hidden dialog title. |
| `description` | `string` | `"Search for a command to run."` | Visually hidden dialog description. |
| `showCloseButton` | `boolean` | `false` |  |
| `className` | `string` | – | Applied to the dialog popup. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-dialog"` | The dialog popup. |
| `data-slot="command-dialog-overlay"` | The backdrop. |
| `data-open` | Present on the popup while it is open. |

### CommandInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Controlled search text. |
| `onValueChange` | `(search: string) => void` | – |  |
| `placeholder` | `string` | – |  |
| `clearLabel` | `string` | `"Clear search"` | Accessible name of the clear button. |
| `backLabel` | `(title: string) => string` | `` (title) => `Back from ${title}` `` | Accessible name of the page chip. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-input"` | The input. |
| `data-slot="command-input-wrapper"` | The row holding the icon, input and clear button. |
| `data-slot="command-clear"` | The clear button, shown once you type. |
| `data-slot="command-page-chip"` | The back chip shown on a page. |

### CommandList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | – | Accessible name of the list. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-list"` | The list. |
| `data-settled` | Present once the list has measured itself. The height transition only runs while it is set. |
| `--cmdk-list-height` | Height of the visible items, used to animate the list. |

### CommandEmpty

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode \| (search: string) => ReactNode` | – | Use the function form to echo the query. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-empty"` | Hidden while a CommandLoading is in the list. |

### CommandLoading

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` | `boolean` | `true` |  |
| `delay` | `number` | `150` | Milliseconds to wait before the spinner shows. |
| `minDuration` | `number` | `300` | Minimum milliseconds the spinner stays once shown. |
| `label` | `string` | – | Accessible label. Defaults to string children. |
| `progress` | `number` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="command-loading"` | The loading row. |
| `data-pending` | Present during the delay, while the row is announced but not yet visible. |

### CommandGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `ReactNode` | – |  |
| `value` | `string` | – | Required when there is no heading. |
| `forceMount` | `boolean` | `false` | Keep the group visible while filtering. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-group"` | The group. |
| `[cmdk-group-heading]` | The heading element. |

### CommandItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSelect` | `(value: string) => void` | – | Runs on click, Enter or the item’s shortcut, after the confirm blink. |
| `value` | `string` | – | Used for filtering. Defaults to the item’s text, without the shortcut. |
| `keywords` | `string[]` | – | Extra words that match this item. |
| `disabled` | `boolean` | `false` |  |
| `shortcut` | `string` | – | A hotkey like "mod+shift+c". Shown on the item and runs it while focus is in the menu. |
| `page` | `string` | – | Opens the CommandPage with this id instead of running. |
| `pageTitle` | `string` | – | Title shown in the page chip. Defaults to the value. |
| `href` | `string` | – | Renders the item as a link. Enter follows it, ⌘ or Ctrl Enter opens a new tab. |
| `render` | `ReactElement` | – | A link element to render instead, like Next.js <Link />. |
| `confirm` | `boolean` | `true` | Blink the item briefly before running it, so the choice registers. |
| `forceMount` | `boolean` | `false` | Keep the item visible while filtering. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-item"` | The item. |
| `data-selected="true"` | Present on the selected item. |
| `data-disabled="true"` | Present on disabled items. |
| `data-value` | The value used for filtering. |
| `data-confirming` | Present during the confirm blink. |
| `data-page` | Present on items that open a page. |

### CommandPage

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | – | Matches the page prop of the item that opens it. Its groups and items only render while it is the current page. |

### CommandShortcut

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hotkey` | `string` | – | Formats a hotkey like "mod+k" for the current platform. Children override it. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-shortcut"` | The shortcut label. |

### CommandSeparator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alwaysRender` | `boolean` | `false` | Keep it visible while searching. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-separator"` | The separator. |

### CommandFooter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | Defaults to key hints that update on a page. Hidden on touch screens. |

| Attribute | Description |
| --- | --- |
| `data-slot="command-footer"` | The footer. |

### useCommandHotkey

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

useCommandHotkey("mod+k", () => setOpen((value) => !value))
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hotkey` | `string` | – | Listened for on the whole document. Hotkeys without a modifier are ignored while typing in a field. |
| `callback` | `(event: KeyboardEvent) => void` | – |  |
| `options.enabled` | `boolean` | `true` |  |

### useCommandLoading

Returns whether a loading indicator should be visible, with the same delay and minimum duration as `<CommandLoading />`. Use it to hide stale results while a request is in flight.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` | `boolean` | – |  |
| `options.delay` | `number` | `150` |  |
| `options.minDuration` | `number` | `300` |  |

### Other hooks

- `useCommandPages()` returns `{ pages, page, push, pop, reset }` to drive pages from your own code.
- `useCommandState(selector)` reads cmdk state, such as the search or the filtered count.
- `useHotkeyLabel(hotkey)` formats a hotkey for the current platform, like ⌘K or Ctrl+K.

---

# Context menu

> A menu of actions on right click or long press, with submenus, checkbox and radio items, and hold feedback on touch.

Docs: https://hextaui.com/docs/context-menu
Markdown: https://hextaui.com/docs/context-menu.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/context-menu.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/context-menu.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuTrigger,
} from "@/components/ui/context-menu"
```

```tsx
<ContextMenu>
  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
  <ContextMenuContent>
    <ContextMenuItem>Profile</ContextMenuItem>
    <ContextMenuItem>Billing</ContextMenuItem>
    <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

## Composition

```text
ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
    ├── ContextMenuGroup
    │   ├── ContextMenuLabel
    │   └── ContextMenuItem
    │       └── ContextMenuShortcut
    ├── ContextMenuCheckboxItem
    ├── ContextMenuRadioGroup
    │   └── ContextMenuRadioItem
    ├── ContextMenuSeparator
    └── ContextMenuSub
        ├── ContextMenuSubTrigger
        └── ContextMenuSubContent
```

## Examples

### File list

Give every row its own menu. The open row keeps a highlight, and a destructive item hands off to an alert dialog for confirmation.

### Controlled

Pass `open` and `onOpenChange` to own the state. The second argument says why it changed, such as `trigger-press`, `outside-press` or `escape-key`. Items with `closeOnClick={false}` keep it open.

### Disabled

A disabled `<ContextMenu />` gives the area back to the browser’s own menu. Disabled items stay visible but are skipped by the keyboard.

### Hold feedback

On touch screens the menu opens after a long press. While the finger is held, the area shrinks slightly so people know the press registered. Moving the finger cancels it. Set `holdFeedback={false}` to turn it off.

### Long content

Long labels wrap inside a 20rem maximum width, and tall menus scroll within the space left in the viewport.

### Nested submenus

Submenus open on hover or with the arrow keys, at any depth. A disabled submenu trigger never opens.

### Inside a sheet

The menu layers above other overlays, and Escape closes only the menu, not the sheet behind it.

### Render as another element

Use `render` to make the trigger any element, such as a figure, or to turn an item into a link.

### Right to left

The menu reads the trigger’s direction, so submenus open to the left and arrow keys flip.

## Keyboard

| Key | Action |
| --- | --- |
| `↓` | Highlights the next item, wrapping at the end. |
| `↑` | Highlights the previous item, wrapping at the start. |
| `Home` | Highlights the first item. |
| `End` | Highlights the last item. |
| `Enter` `Space` | Runs the highlighted item. Checkbox and radio items toggle and keep the menu open. |
| `→` | Opens the highlighted submenu and moves into it. ← in right-to-left layouts. |
| `←` | Closes the current submenu and returns to its trigger. → in right-to-left layouts. |
| `Esc` | Closes the current menu. In a submenu, only that submenu closes. |
| `A–Z` | Highlights the next item starting with that letter. |

## Accessibility

- A context menu is a shortcut. Make every action in it reachable some other way too, such as a visible button or a dropdown menu, since many people never right click or long press.
- Browsers also fire the context menu event for Shift F10 and the Menu key on a focused element, so a focusable element inside the trigger lets keyboard users open it.
- Shortcuts in `<ContextMenuShortcut />` are labels only. Bind the keys yourself.
- With reduced motion on, the hold feedback and the item blink are skipped and the menu only fades.

## API reference

Built on the Base UI context menu. Every part accepts the props of the primitive it wraps, and a function `className` that receives the part’s state.

### ContextMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – | details.reason says what caused the change. |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Runs after the open or close animation ends. |
| `disabled` | `boolean` | `false` | Shows the browser’s native menu instead. |
| `loopFocus` | `boolean` | `true` | Wrap arrow-key navigation at the ends. |
| `highlightItemOnHover` | `boolean` | `true` |  |
| `actionsRef` | `RefObject<{ close, unmount }>` | – | Close the menu imperatively. |

### ContextMenuTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `holdFeedback` | `boolean` | `true` | Shrink the area slightly while a long press is held on touch screens. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-trigger"` | Target the trigger in CSS. |
| `data-popup-open` | Present while its menu is open. |
| `data-holding` | Present while a long press is held. |
| `data-pressed` | Present while the trigger is pressed. |

### ContextMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left" \| "inline-start" \| "inline-end"` | `"bottom"` | Preferred side, relative to the pointer. |
| `align` | `"start" \| "center" \| "end"` | `"start"` |  |
| `sideOffset` | `number` | `0` |  |
| `alignOffset` | `number` | `0` |  |
| `collisionPadding` | `number \| { top, right, bottom, left }` | – | Space to keep between the menu and the viewport edges. |
| `collisionAvoidance` | `CollisionAvoidance` | – | How the menu flips or shifts when it would overflow. |
| `anchor` | `Element \| VirtualElement \| RefObject` | – | Position against something other than the pointer. |
| `finalFocus` | `boolean \| RefObject \| (closeType) => HTMLElement \| boolean` | – | Where focus goes after the menu closes. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-content"` | The menu popup. |
| `data-open` | Present while open. |
| `data-starting-style` | Present while the menu animates in. |
| `data-ending-style` | Present while the menu animates out. |
| `data-side` | The side it was placed on after collisions. |
| `data-chosen` | Present after an item is clicked. The fade-out waits for the blink. |
| `--transform-origin` | The point the scale animation grows from. |
| `--available-height` | Space left in the viewport. Caps the menu height. |

### ContextMenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` |  |
| `inset` | `boolean` | `false` | Indent the label to line up with checkbox items. |
| `onClick` | `(event) => void` | – | Runs on click, Enter or Space. The menu closes after a short blink. |
| `closeOnClick` | `boolean` | `true` |  |
| `disabled` | `boolean` | `false` |  |
| `label` | `string` | – | Text used for typeahead when children are not plain text. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-item"` | Target items in CSS. |
| `data-variant` | The current variant. |
| `data-highlighted` | Present on the item under the pointer or keyboard focus. |
| `data-disabled` | Present when the item is disabled. |
| `data-inset` | Present when inset is set. |
| `data-chosen` | Present on the clicked item while it blinks. |

### ContextMenuCheckboxItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – |  |
| `defaultChecked` | `boolean` | `false` |  |
| `onCheckedChange` | `(checked: boolean, details) => void` | – |  |
| `closeOnClick` | `boolean` | `false` |  |
| `inset` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-checkbox-item"` | Target checkbox items in CSS. |
| `data-checked` | Present when checked. |
| `data-unchecked` | Present when unchecked. |
| `data-highlighted` | Present on the item under the pointer or keyboard focus. |
| `data-disabled` | Present when the item is disabled. |
| `data-inset` | Present when inset is set. |
| `data-chosen` | Present on the clicked item while it blinks. |

### ContextMenuRadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | – |  |
| `defaultValue` | `any` | – |  |
| `onValueChange` | `(value: any, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |

### ContextMenuRadioItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | – |  |
| `closeOnClick` | `boolean` | `false` |  |
| `inset` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-radio-item"` | Target radio items in CSS. |
| `data-checked` | Present when selected. |
| `data-highlighted` | Present on the item under the pointer or keyboard focus. |
| `data-disabled` | Present when the item is disabled. |
| `data-inset` | Present when inset is set. |
| `data-chosen` | Present on the clicked item while it blinks. |

### ContextMenuLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

Inside `<ContextMenuGroup />` or `<ContextMenuRadioGroup />` it labels the group for assistive tech. Elsewhere it is a plain heading.

### ContextMenuSub

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |
| `closeParentOnEsc` | `boolean` | `false` | Close the whole menu on Escape, not just this submenu. |

### ContextMenuSubTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | `false` |  |
| `openOnHover` | `boolean` | `true` |  |
| `delay` | `number` | `100` | Milliseconds of hover before the submenu opens. |
| `closeDelay` | `number` | `0` |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-sub-trigger"` | Target submenu triggers in CSS. |
| `data-popup-open` | Present while its submenu is open. |
| `data-highlighted` | Present while highlighted. |
| `data-disabled` | Present when disabled. |

### ContextMenuSubContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left" \| "inline-start" \| "inline-end"` | – | Opens toward the inline end by default. |
| `align` | `"start" \| "center" \| "end"` | – |  |
| `sideOffset` | `number` | `0` |  |
| `alignOffset` | `number` | `-4` |  |
| `collisionPadding` | `number \| { top, right, bottom, left }` | – | Space to keep between the menu and the viewport edges. |
| `collisionAvoidance` | `CollisionAvoidance` | – | How the menu flips or shifts when it would overflow. |
| `anchor` | `Element \| VirtualElement \| RefObject` | – | Position against something other than the pointer. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-sub-content"` | The submenu popup. Takes the same state attributes as the menu. |

### ContextMenuShortcut

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dir` | `"ltr" \| "rtl"` | `"ltr"` | Keeps shortcuts like ⇧⌘S in order inside right-to-left menus. |

| Attribute | Description |
| --- | --- |
| `data-slot="context-menu-shortcut"` | The shortcut label. |

### ContextMenuGroup and ContextMenuSeparator

`<ContextMenuGroup />` groups related items under a label. `<ContextMenuSeparator />` draws a divider. Both accept `render` and `className`, and carry `context-menu-group` and `context-menu-separator` as their `data-slot`.

---

# Data table

> A table for real data, with sorting, search, row selection, pinned columns, a sticky header and pagination.

Docs: https://hextaui.com/docs/data-table
Markdown: https://hextaui.com/docs/data-table.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/data-table.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react @tanstack/react-table class-variance-authority cn
```

Copy `components/ui/data-table.tsx`, `components/ui/table.tsx`, `components/ui/button.tsx`, `components/ui/checkbox.tsx`, `components/ui/skeleton.tsx` into your project. Their source is in this page's Markdown.

## Usage

The data table is TanStack Table v9 with the sorting, filtering, pagination, selection and column visibility features already wired up. Define columns once with `createDataTableColumns`, create the table with `useDataTable`, then compose the parts you need.

```tsx
import {
  createDataTableColumns,
  DataTable,
  DataTableColumnHeader,
  DataTableContent,
  DataTablePagination,
  DataTableSearch,
  DataTableSelectAll,
  DataTableSelectRow,
  DataTableToolbar,
  DataTableViewOptions,
  useDataTable,
} from "@/components/ui/data-table"
```

```tsx
type Payment = { id: string; email: string; amount: number }

const helper = createDataTableColumns<Payment>()

const columns = helper.columns([
  helper.display({
    id: "select",
    header: ({ table }) => <DataTableSelectAll table={table} />,
    cell: ({ row }) => <DataTableSelectRow row={row} />,
    enableSorting: false,
    enableHiding: false,
  }),
  helper.accessor("email", {
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Email" />
    ),
  }),
  helper.accessor("amount", {
    header: "Amount",
    meta: { align: "end" },
  }),
])
```

```tsx
export function Payments({ data }: { data: Payment[] }) {
  const table = useDataTable({
    data,
    columns,
    getRowId: (row) => row.id,
  })

  return (
    <DataTable table={table}>
      <DataTableToolbar>
        <DataTableSearch placeholder="Search payments…" />
        <DataTableViewOptions />
      </DataTableToolbar>
      <DataTableContent />
      <DataTablePagination />
    </DataTable>
  )
}
```

Pass any TanStack state you want to own, such as sorting or row selection, with its change handler.

```tsx
const [sorting, setSorting] = React.useState([{ id: "date", desc: true }])

const table = useDataTable({
  data,
  columns,
  state: { sorting },
  onSortingChange: setSorting,
})
```

## Composition

```text
DataTable
├── DataTableToolbar
│   ├── DataTableSearch
│   └── DataTableViewOptions
├── DataTableContent
└── DataTablePagination
```

`DataTableColumnHeader`, `DataTableSelectAll` and `DataTableSelectRow` go in your column definitions, as a column’s header or cell.

## Examples

### Plain table

The plain `<Table />` parts the data table is built from. Use them on their own for static data, with a caption and a footer total.

### Loading

With `loading`, skeleton rows fill the same space as real rows, so nothing jumps when the data arrives. The table is marked `aria-busy` meanwhile.

### Empty

`emptyMessage` fills the body when there is no data or nothing matches the search.

### Sticky header

Give the container a max height with `containerClassName` and set `stickyHeader`. The header stays put and gains a hairline once the rows scroll under it. Shift-drag over the checkboxes scrolls the box as you near its edge.

### Pinned columns

The selection column and the first data column are pinned by default. Choose your own with `pinStart`. A soft shadow marks the edge once the table scrolls sideways.

### Right to left

Every label and count can be replaced with `labels` and the format functions. Pagination arrows and pinned columns flip with the direction.

## Interactions

- Click a sortable header to sort ascending, again for descending, and a third time to clear. Shift-click another header to add a secondary sort.
- Shift-click a row checkbox to select every row between it and the last one you clicked. Hold Shift and drag across checkboxes to select or clear a range in one motion.
- Searching matches every column except the selection column and jumps back to the first page.
- Hiding columns from the View menu keeps the menu open, so you can toggle several at once.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves through the search, View menu, sortable headers, row checkboxes and pagination. |
| `Enter` `Space` | Sorts by the focused header. |
| `Space` | Toggles the focused checkbox. |
| `Esc` | Clears the search when it has text. |

## Accessibility

- Sortable headers carry `aria-sort`, and a polite live region announces the new sort and, shortly after typing, the number of results.
- The page indicator is a live region, so screen readers hear the new page after pressing next or previous.
- Checkboxes have labels by default. Override them with `aria-label` on `<DataTableSelectAll />` and `<DataTableSelectRow />`.

## API reference

Every part below has to be rendered inside `<DataTable />`, which shares the table with them.

### useDataTable

Takes the TanStack Table options and returns the table. Pages hold 10 rows unless `initialState.pagination` says otherwise.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `TData[]` | – |  |
| `columns` | `ColumnDef[]` | – | Build them with createDataTableColumns. |
| `getRowId` | `(row: TData) => string` | – | Keeps selection stable when rows move. Defaults to the row index. |
| `initialState` | `Partial<TableState>` | `{ pagination: { pageIndex: 0, pageSize: 10 } }` |  |
| `state` | `Partial<TableState>` | – | Control sorting, rowSelection, globalFilter, pagination or columnVisibility. |
| `onSortingChange` | `OnChangeFn<SortingState>` | – | Each controllable state has a matching handler, like onRowSelectionChange. |
| `enableRowSelection` | `boolean \| (row) => boolean` | `true` |  |

### createDataTableColumns

Returns a typed column helper with `accessor`, `display` and `columns`. Set `meta: { align: "end" }` on numeric columns to align the header and cells.

### DataTable

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `table` | `DataTableInstance<TData>` | – | The table returned by useDataTable. |
| `className` | `string` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="data-table"` | The wrapper around every part. |
| `data-slot="data-table-announcer"` | The visually hidden live region. |

### DataTableContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `emptyMessage` | `ReactNode` | `"No results."` |  |
| `loading` | `boolean` | `false` |  |
| `loadingRows` | `number` | `5` | Number of skeleton rows while loading. |
| `pinStart` | `string[]` | `["select", firstColumnId]` | Column ids to pin to the start edge. |
| `stickyHeader` | `boolean` | `false` | Needs a max height on the container. |
| `containerClassName` | `string` | – | Applied to the scroll container. |
| `swipeSelect` | `boolean` | `true` | Shift-drag across checkboxes to select a range. |
| `className` | `string` | – | Applied to the table element. |

| Attribute | Description |
| --- | --- |
| `data-slot="table-container"` | The scroll container. |
| `data-scrolled-start` | Present on the container when it has scrolled away from the start edge. |
| `data-scrolled-end` | Present while there is more to scroll toward the end edge. |
| `data-scrolled-top` | Present once the rows scroll vertically. |
| `data-swipe-selecting` | Present on the container during a shift-drag. |
| `data-state="selected"` | Present on selected rows. |
| `data-row-id` | The row id from getRowId. |
| `data-slot="data-table-loading-row"` | Each skeleton row. |
| `data-slot="data-table-empty"` | The empty row. |

### DataTableToolbar

A wrapping row for the search, the View menu and your own filters. Accepts every `div` prop and carries `data-table-toolbar` as its `data-slot`.

### DataTableSearch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `string` | `"Search…"` |  |
| `aria-label` | `string` | `"Search table"` |  |
| `clearLabel` | `string` | `"Clear search"` | Accessible name of the clear button. |

| Attribute | Description |
| --- | --- |
| `data-slot="data-table-search"` | The search field wrapper. |

### DataTableViewOptions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"View"` |  |
| `groupLabel` | `string` | `"Toggle columns"` |  |
| `getLabel` | `(column) => string` | – | Defaults to the column’s string header, or its id capitalized. |

Lists every column that can hide. Set `enableHiding: false` on a column to leave it out.

| Attribute | Description |
| --- | --- |
| `data-slot="data-table-view-options"` | The menu popup. |

### DataTableColumnHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `column` | `Column` | – |  |
| `title` | `string` | – |  |

Renders a sort button for sortable columns and plain text for the rest.

| Attribute | Description |
| --- | --- |
| `data-slot="data-table-column-header"` | The header wrapper. |
| `data-sorted` | Present on the sort button while the column is sorted. |
| `aria-sort` | On the header cell: ascending, descending or none. |

### DataTableSelectAll

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `table` | `Table` | – |  |
| `aria-label` | `string` | `"Select all rows on this page"` |  |

Selects the rows on the current page and shows an indeterminate state when only some are selected.

### DataTableSelectRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `row` | `Row` | – |  |
| `aria-label` | `string` | `"Select row"` |  |

### DataTablePagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pageSizes` | `number[]` | `[10, 20, 50, 100]` |  |
| `showSelection` | `boolean` | `true` | Show the selected count instead of the row count. |
| `labels` | `Partial<DataTablePaginationLabels>` | – | rowsPerPage, firstPage, previousPage, nextPage and lastPage. |
| `formatSelection` | `(selected: number, total: number) => ReactNode` | `"2 of 42 rows selected"` |  |
| `formatRows` | `(total: number) => ReactNode` | `"42 rows"` |  |
| `formatPage` | `(page: number, pageCount: number) => ReactNode` | `"Page 1 of 5"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="data-table-pagination"` | The pagination bar. |

### useDataTableContext

Returns the table from the nearest `<DataTable />`. Use it to build your own toolbar controls, such as a status filter.

### Table

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stickyHeader` | `boolean` | `false` | Pins the header row inside a scrolling container. |
| `containerClassName` | `string` | – | Applied to the scroll container. |
| `containerRef` | `Ref<HTMLDivElement>` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="table"` | The table element. |
| `data-sticky-header` | Present on the container when stickyHeader is on. |
| `--table-bg` | Row and pinned-cell background. Follows the card or popover it sits in. |

### TableHead and TableCell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | End-aligned cells also use tabular numbers. |
| `pinned` | `"start" \| "end"` | – | Keeps the cell in place while the table scrolls sideways. Offset with --pin-offset. |
| `pinnedEdge` | `boolean` | `false` | Draws a soft shadow on the last pinned column while scrolled. |

| Attribute | Description |
| --- | --- |
| `data-align` | The current alignment. |
| `data-pinned` | start or end when pinned. |
| `data-pinned-edge` | Present on the last pinned cell of a side. |
| `--pin-offset` | Distance from the pinned edge, set for you. |

### Other table parts

`TableHeader`, `TableBody`, `TableFooter`, `TableRow` and `TableCaption` render the matching table elements and accept all of their props.

---

# Date picker

> A button that opens a calendar in a popover, or a bottom sheet on phones, for single dates and ranges.

Docs: https://hextaui.com/docs/date-picker
Markdown: https://hextaui.com/docs/date-picker.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/date-picker.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn react-day-picker
```

Copy `components/ui/date-picker.tsx`, `components/ui/calendar.tsx`, `components/ui/popover.tsx`, `components/ui/sheet.tsx`, `components/ui/button.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { DatePicker, DateRangePicker } from "@/components/ui/date-picker"
```

```tsx
const [date, setDate] = React.useState<Date | null>(null)

<DatePicker value={date} onValueChange={setDate} />
```

On screens narrower than 640px the calendar opens in a bottom sheet instead of a popover, so days stay large enough to tap.

## Examples

### Controlled

Pass `value` and `onValueChange`. Cleared values are `null`. The calendar always opens on the month of the selected date, and picking a day closes it and returns focus to the button.

### Range

`<DateRangePicker />` shows two months on larger screens. The first click always starts a new range, even when one is set, and the second click finishes it in either order and closes the picker.

### Disabled days

Pass any react-day-picker matcher as `calendarProps.disabled`. Here only future weekdays can be picked.

### Month and year dropdowns

For far-away dates like a birthday, set `captionLayout: "dropdown"` with a `startMonth` and `endMonth`. Label the trigger with a `<label />` pointing at its `id`.

### In a form

With `name`, a single date is submitted as `2026-10-14` and a range as `2026-10-20/2026-10-24`. Empty pickers submit an empty string.

### Disabled

A disabled trigger can still show a value.

### Narrow container

The trigger never grows past its container. Long labels truncate instead of wrapping.

### Inside a sheet

The picker layers above the sheet, and Escape closes only the picker.

### Right to left

Pass `locale` for the trigger label and a react-day-picker locale with `dir: "rtl"` in `calendarProps` for the calendar. Arrow keys follow the direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | On the trigger, opens the picker and focuses the selected day, or today. On a day, selects it. |
| `←` `→` | Moves to the previous or next day. |
| `↑` `↓` | Moves to the same day in the previous or next week. |
| `Page Up` `Page Down` | Moves to the previous or next month. |
| `Shift` `Page Up` | Moves to the previous year. Shift Page Down moves to the next. |
| `Home` `End` | Moves to the start or end of the week. |
| `Esc` | Closes the picker and returns focus to the trigger. |

## Accessibility

- The popover is labelled with `title`, and the bottom sheet shows it as a heading. Translate it along with `placeholder`.
- The trigger has no visible label of its own. Pair it with a `<label />` or pass `aria-label`.
- Disabled days are skipped by the keyboard and announced as unavailable.

## API reference

Both pickers share the props below and render a `<Button />` trigger with a `<Calendar />` in a popover or bottom sheet.

### DatePicker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Date \| null` | – |  |
| `defaultValue` | `Date \| null` | `null` |  |
| `onValueChange` | `(value: Date \| null) => void` | – |  |
| `placeholder` | `string` | `"Pick a date"` |  |
| `title` | `string` | `"Select a date"` | Accessible name of the popover, heading of the sheet. |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` | – |  |
| `locale` | `string` | `"en-US"` | Formats the trigger label with Intl.DateTimeFormat. Pass a react-day-picker locale in calendarProps to translate the calendar too. |
| `clearable` | `boolean` | `false` | Adds a Clear button below the calendar once there is a value. |
| `clearLabel` | `string` | `"Clear"` |  |
| `name` | `string` | – | Renders a hidden input so the value is submitted with its form. |
| `calendarProps` | `CalendarProps` | – | Passed to the calendar, except mode, selected, onSelect, required, numberOfMonths and autoFocus. Use it for disabled days, captionLayout, startMonth, endMonth, locale and dir. |
| `variant` | `Button variant` | `"outline"` | The trigger is a Button, and accepts its other props too. |
| `disabled` | `boolean` | `false` |  |
| `className` | `string` | – | Applied to the trigger, which is w-60 by default. |

### DateRangePicker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `{ from: Date; to?: Date } \| null` | – |  |
| `defaultValue` | `{ from: Date; to?: Date } \| null` | `null` |  |
| `onValueChange` | `(value: DateRange \| null) => void` | – | Called once the second day is picked. |
| `placeholder` | `string` | `"Pick a date range"` |  |
| `title` | `string` | `"Select dates"` |  |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean) => void` | – |  |
| `locale` | `string` | `"en-US"` | Formats the trigger label with Intl.DateTimeFormat. Pass a react-day-picker locale in calendarProps to translate the calendar too. |
| `clearable` | `boolean` | `false` | Adds a Clear button below the calendar once there is a value. |
| `clearLabel` | `string` | `"Clear"` |  |
| `name` | `string` | – | Renders a hidden input so the value is submitted with its form. |
| `calendarProps` | `CalendarProps` | – | Passed to the calendar, except mode, selected, onSelect, required, numberOfMonths and autoFocus. Use it for disabled days, captionLayout, startMonth, endMonth, locale and dir. |
| `variant` | `Button variant` | `"outline"` | The trigger is a Button, and accepts its other props too. |
| `disabled` | `boolean` | `false` |  |
| `className` | `string` | – | Applied to the trigger, which is w-60 by default. |

### Data attributes

| Attribute | Description |
| --- | --- |
| `data-slot="date-picker-trigger"` | The trigger button. |
| `data-empty` | Present on the trigger while there is no value. Shows the placeholder in muted text. |
| `data-popup-open` | Present on the trigger while the picker is open. |
| `data-slot="date-picker-content"` | Wraps the calendar in the popover or sheet. |
| `data-slot="date-picker-clear"` | The Clear button. |

---

# Dialog

> A window over the page for forms and focused tasks, with a pinned header and footer, nesting, and a swipeable bottom sheet on phones.

Docs: https://hextaui.com/docs/dialog
Markdown: https://hextaui.com/docs/dialog.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/dialog.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/dialog.tsx`, `components/ui/sheet.tsx`, `components/ui/button.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
```

```tsx
<Dialog>
  <DialogTrigger render={<Button variant="outline" />}>Open</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
      <DialogDescription>Make changes to your profile.</DialogDescription>
    </DialogHeader>
    <DialogBody>{/* fields */}</DialogBody>
    <DialogFooter>
      <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
      <Button>Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Composition

```text
Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    ├── DialogBody
    └── DialogFooter
        └── DialogClose
```

## Examples

### Form

Keep the form in `<DialogBody />` and point the submit button in the footer at it with `form`. Enter submits, and the dialog closes through `onOpenChange` once the value is saved.

### Custom close button

Hide the corner button with `showCloseButton={false}` on the content and add a Close button to the footer with `showCloseButton`.

### No close button

Without a button the dialog still closes with Esc, a click outside, or a swipe down on phones.

### Sizes

`size` sets the maximum width on larger screens: `sm`, `default` or `lg`.

### Sticky footer

Long content in `<DialogBody />` scrolls while the header and footer stay in place, so the actions are always in reach.

### Scrollable content

Without a footer the body scrolls under the header and keeps its bottom padding.

### Controlled

Pass `open` and `onOpenChange` to open it from code, without a trigger.

### Nested

A dialog or alert dialog opened from inside another stacks on top. The parent steps back and a lighter backdrop covers it. Esc closes only the top one.

### Detached triggers

Create a handle with `createDialogHandle()` to share one dialog between many triggers. Each trigger passes a `payload` that the dialog reads through a render function.

### Right to left

Pass `dir` to the content as well, because it renders in a portal outside your RTL container.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | On the trigger, opens the dialog and moves focus to its first control. |
| `Tab` `Shift+Tab` | Moves focus between controls. Focus stays inside. |
| `Esc` | Closes the top dialog and returns focus to its trigger. |

## Accessibility

- The content has `role="dialog"` and is labelled by its title and described by its description. Always include a `<DialogTitle />`.
- With a mouse or keyboard, focus starts on the first control. With touch it starts on the dialog itself, so the on-screen keyboard doesn’t cover the content before people choose a field. Pass `initialFocus` to change it.
- The corner close button is labelled “Close”, and the page behind is inert and can’t scroll.
- On phones it becomes a bottom sheet that can be swiped down to close. With reduced motion on, it fades instead of scaling or sliding.

## API reference

Built on the Base UI drawer, through `<Sheet />`. Every part accepts the props of the primitive or element it wraps.

### Dialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the open or close animation. |
| `modal` | `boolean \| "trap-focus"` | `true` |  |
| `disablePointerDismissal` | `boolean` | `false` | Keeps the dialog open on clicks outside. |
| `handle` | `DialogHandle<Payload>` | – | Connects detached triggers. |
| `actionsRef` | `RefObject<{ close, unmount }>` | – | Close or unmount the dialog imperatively. |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – |  |

### DialogTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DialogHandle<Payload>` | – |  |
| `payload` | `Payload` | – | Passed to the dialog’s render function. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-trigger"` | Target triggers in CSS. |
| `data-popup-open` | Present while its dialog is open. |

### DialogContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `showCloseButton` | `boolean` | `true` | Shows the close button in the corner. |
| `initialFocus` | `boolean \| RefObject \| (openType) => HTMLElement \| boolean` | `First control, or the dialog on touch` |  |
| `finalFocus` | `boolean \| RefObject \| (closeType) => HTMLElement \| boolean` | `The trigger` |  |
| `dir` | `"ltr" \| "rtl"` | – | Set it when the dialog should be right to left. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-content"` | Target the dialog in CSS. |
| `data-size` | The current size. |
| `data-open` | Present while open. |
| `data-starting-style` | Present while the dialog animates in. |
| `data-ending-style` | Present while the dialog animates out. |
| `data-nested-drawer-open` | Present while a nested dialog is open on top. |
| `data-swiping` | Present while it is being swiped on a phone. |
| `--nested-drawers` | How many dialogs are open on top of this one. |

### DialogHeader

A `<div>` that stacks the title and description. It leaves room for the close button.

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-header"` | Target the header in CSS. |

### DialogBody

A `<div>` that scrolls when the content is taller than the screen, keeping the header and footer in place.

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-body"` | Target the body in CSS. |

### DialogFooter

A `<div>` for the actions. Buttons stack full width on phones, with the first one at the bottom.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showCloseButton` | `boolean` | `false` | Adds an outline Close button after the children. |

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-footer"` | Target the footer in CSS. |

### DialogTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<h2>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-title"` | Target the title in CSS. |

### DialogDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` | Use render={<div />} when it holds several paragraphs. |

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-description"` | Target the description in CSS. |

### DialogClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dialog-close"` | Target close buttons in CSS. |

### DialogPortal and DialogOverlay

`<DialogContent />` already renders both. Use them only when composing a custom popup.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keepMounted` | `boolean` | `false` | On the portal, keeps the dialog in the DOM while closed. |

### createDialogHandle

Returns a handle that connects `<DialogTrigger />` elements anywhere on the page to one `<Dialog />`. Type the payload with a generic: `createDialogHandle<{ name: string }>()`.

---

# Drawer

> A panel that slides in from any edge and follows your finger, with snap points, a working handle and nested drawers that stack.

Docs: https://hextaui.com/docs/drawer
Markdown: https://hextaui.com/docs/drawer.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/drawer.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react cn
```

Copy `components/ui/drawer.tsx`, `components/ui/sheet.tsx`, `components/ui/button.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Drawer,
  DrawerBody,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@/components/ui/drawer"
```

```tsx
<Drawer>
  <DrawerTrigger render={<Button variant="outline" />}>Open</DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>Are you absolutely sure?</DrawerTitle>
      <DrawerDescription>This action cannot be undone.</DrawerDescription>
    </DrawerHeader>
    <DrawerBody>{/* content */}</DrawerBody>
    <DrawerFooter>
      <Button>Submit</Button>
      <DrawerClose render={<Button variant="outline" />}>Cancel</DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

## Composition

```text
Drawer
├── DrawerTrigger
└── DrawerContent
    ├── DrawerHeader
    │   ├── DrawerTitle
    │   └── DrawerDescription
    ├── DrawerBody
    └── DrawerFooter
        └── DrawerClose
```

## Examples

### Directions

Set `swipeDirection` on `<Drawer />` to pick the edge. The drawer opens from that edge and swipes back towards it. Top and bottom drawers show a handle by default.

### Snap points

Pass `snapPoints` to rest a bottom drawer at preset heights. Numbers from 0 to 1 are fractions of the viewport, larger numbers are pixels, and strings take px or rem. The visible part always fits its content, so nothing hides below the screen.

### Scrollable content

`<DrawerBody />` scrolls on its own, so the header and footer stay in place. Swiping only starts once the body is scrolled back to the top.

### Forms and the keyboard

Wrap `<DrawerContent />` in `<DrawerVirtualKeyboardProvider />` when a bottom drawer holds text fields. On phones, the focused field scrolls into view above the software keyboard instead of hiding behind it. Keep the fields in `<DrawerBody />` so the header and footer stay put.

### Nested

A drawer opened from a drawer on the same edge stacks on top. The ones behind shrink, peek out above it and follow your finger as you swipe the top one away.

### Confirm from a drawer

Dialogs, alert dialogs, sheets and drawers on another edge layer on top instead of stacking. The drawer steps back and a lighter backdrop covers it.

### Responsive

Change `swipeDirection` with a media query to show a side panel on desktop and a bottom sheet on phones.

### Non-modal

With `modal={false}` there is no backdrop, the page keeps scrolling and focus can leave the drawer.

### Controlled

Pass `open` and `onOpenChange` to open it from anywhere, without a trigger.

### Detached triggers

Share one drawer between several triggers with `createDrawerHandle`. Each trigger passes a `payload` that the drawer renders through a function child.

### Right to left

Pass `dir="rtl"` to `<DrawerContent />` to mirror its content. `swipeDirection` names a physical edge, so `"left"` stays on the left and the handle stays on the inner edge.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | On the trigger, opens the drawer and moves focus inside it. |
| `Tab` `Shift + Tab` | Moves between focusable elements. Focus stays inside a modal drawer. |
| `Esc` | Closes the topmost drawer and returns focus to its trigger. |

## Accessibility

- The drawer is a dialog. `<DrawerTitle />` labels it and `<DrawerDescription />` describes it, so always include a title.
- Swiping is never the only way out: Escape, the backdrop and a `<DrawerClose />` button all close it too.
- The handle is decorative and hidden from assistive tech. With a mouse, text inside the drawer can be selected without dragging it.
- With reduced motion enabled, the drawer fades in and out instead of sliding. Dragging still follows the pointer.

## API reference

Built on the Base UI drawer. Every part accepts the props of the primitive it wraps.

### Drawer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `swipeDirection` | `"up" \| "down" \| "left" \| "right"` | `"down"` | The edge it opens from and the direction that dismisses it. |
| `showSwipeHandle` | `boolean` | – | Shows the handle. Defaults to true for up and down, false for left and right. |
| `snapPoints` | `(number \| string)[]` | – | Heights a vertical drawer can rest at. 0–1 is a fraction of the viewport, >1 is pixels, strings take px or rem. |
| `snapPoint` | `number \| string \| null` | – |  |
| `defaultSnapPoint` | `number \| string \| null` | – |  |
| `onSnapPointChange` | `(snapPoint, details) => void` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `open` | `boolean` | – |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the open or close animation ends. |
| `modal` | `boolean \| "trap-focus"` | `true` | The backdrop only renders when true. |
| `disablePointerDismissal` | `boolean` | `false` | Keep it open when the backdrop is clicked. |
| `handle` | `DrawerHandle<Payload>` | – |  |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – |  |

### DrawerTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `DrawerHandle<Payload>` | – |  |
| `payload` | `Payload` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-trigger"` | Target the trigger in CSS. |
| `data-popup-open` | Present while its drawer is open. |

### DrawerContent

Renders the portal, backdrop, viewport and popup, plus the handle. Vertical drawers fit their content up to the viewport height minus 4rem. Side drawers are 75% wide, up to 24rem from the sm breakpoint. Override with `h-*` or `w-*`, or scope it to one axis with `data-[swipe-axis=y]:`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `initialFocus` | `boolean \| RefObject \| (type) => HTMLElement \| boolean` | – |  |
| `finalFocus` | `boolean \| RefObject \| (type) => HTMLElement \| boolean` | – |  |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-popup"` | The drawer panel. |
| `data-slot="drawer-content"` | The inner wrapper around your children. It scrolls when nothing else does. |
| `data-swipe-direction` | up, right, down or left. |
| `data-swipe-axis` | x or y. |
| `data-open` | Present while the drawer is open. |
| `data-starting-style` | Present while it animates in. |
| `data-ending-style` | Present while it animates out. |
| `data-swiping` | Present while it is being dragged. |
| `data-snap-points` | Present when the drawer has snap points. |
| `data-expanded` | Present at the full-height snap point. |
| `data-nested-drawer-open` | Present while another drawer is open on top. |
| `data-stack` | Present while a drawer on the same edge is stacked on top. |
| `--drawer-inset` | Floats the drawer away from the viewport edges. Defaults to 0px. |
| `--drawer-bleed-background` | Fills the area revealed when dragged past its edge. Defaults to the popover color. |
| `--drawer-swipe-movement-x` | Horizontal drag distance. A -y variable exists too. |
| `--drawer-snap-point-offset` | How far the current snap point sits below the top. |
| `--nested-drawers` | How many drawers are open on top. |

### DrawerOverlay

Rendered by `<DrawerContent />` when `modal` is true. It fades as you swipe, and stays at least half visible when there are snap points. A drawer layered over a sheet or a drawer on another edge gets a lighter backdrop.

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-overlay"` | The backdrop. |
| `data-nested` | Present on lighter backdrops of layered drawers. |
| `--drawer-overlay-min-opacity` | The lowest opacity it fades to while swiping. 0, or 0.5 with snap points. |

### DrawerSwipeHandle

Rendered by `<DrawerContent />` on the inner edge when `showSwipeHandle` is on. The whole drawer can be dragged, so the handle is a visual cue.

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-swipe-handle"` | The handle. |

### DrawerHeader, DrawerBody, DrawerFooter

Plain `<div>` elements that lay out the drawer. The header centers its text in vertical drawers on small screens, the body scrolls and takes the remaining space, and the footer stacks its actions.

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-header"` | Title and description. |
| `data-slot="drawer-body"` | Scrollable content. |
| `data-slot="drawer-footer"` | Actions. |

### DrawerTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<h2>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-title"` | Labels the drawer. |

### DrawerDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-description"` | Describes the drawer. |

### DrawerVirtualKeyboardProvider

Renders no element. Place it inside `<Drawer />`, around `<DrawerContent />`. While the software keyboard is open, it adds room below the drawer’s scroll container, scrolls the focused field into view, and makes taps on fields open the keyboard on iOS. Drawers without it are unaffected.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – |  |

| Attribute | Description |
| --- | --- |
| `--drawer-keyboard-inset` | Set on the viewport while the keyboard is open: how much of it overlaps the page. Use it with a 0px fallback. |

### DrawerClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="drawer-close"` | Closes the drawer when pressed. |

### createDrawerHandle

`createDrawerHandle<Payload>()` returns a handle that connects a `<Drawer />` to triggers rendered elsewhere. Create it once, outside your component.

---

# Dropdown menu

> A menu of actions and options behind a button, with groups, submenus, checkbox and radio items, and shortcuts.

Docs: https://hextaui.com/docs/dropdown-menu
Markdown: https://hextaui.com/docs/dropdown-menu.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/dropdown-menu.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/dropdown-menu.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
```

```tsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
    Open
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuItem>Billing</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">Log out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Composition

```text
DropdownMenu
├── DropdownMenuTrigger
└── DropdownMenuContent
    ├── DropdownMenuGroup
    │   ├── DropdownMenuLabel
    │   └── DropdownMenuItem
    │       └── DropdownMenuShortcut
    ├── DropdownMenuCheckboxItem
    ├── DropdownMenuRadioGroup
    │   └── DropdownMenuRadioItem
    ├── DropdownMenuSeparator
    └── DropdownMenuSub
        ├── DropdownMenuSubTrigger
        └── DropdownMenuSubContent
```

## Examples

### Safe area

Moving diagonally from a submenu trigger toward its submenu crosses sibling triggers. The safe area keeps the submenu open while the pointer heads into it. Turn on `showSafeArea` to see it live: the dot turns green inside the area and red where the submenu would switch.

### Checkboxes

`<DropdownMenuCheckboxItem />` toggles a setting and keeps the menu open, so several can be changed in a row. The check draws in and out instead of popping.

### Radio group

Wrap `<DropdownMenuRadioItem />` in a `<DropdownMenuRadioGroup />` to pick one option. A label inside the group names it for screen readers.

### Select-like

The menu is never narrower than its trigger. Set `closeOnClick` on radio items when picking one should also close the menu.

### Row actions

One menu serves every row. Create a handle with `createDropdownMenuHandle`, pass it to each trigger with a `payload`, and read the payload in the menu. Delete hands off to an alert dialog.

### Controlled

Pass `open` and `onOpenChange`. The second argument says why the menu changed, such as a trigger press, an item press or Escape. Items with `closeOnClick={false}` keep it open.

### Open on hover

`openOnHover` on the trigger opens the menu after `delay` and closes it after `closeDelay`. Clicking and the keyboard still work, so touch and keyboard users aren’t locked out.

### Disabled

A disabled trigger never opens. Disabled items stay visible and are skipped by the arrow keys.

### Long content

Labels wrap instead of stretching the menu past 20rem, unbroken strings break anywhere, and shortcuts stay on the first line.

### Scrolling

When there isn’t room for every item, the menu scrolls inside the viewport and the highlighted item scrolls into view.

### Inside a sheet

The menu layers above the sheet. Escape closes the menu first, then the sheet.

### Right to left

The menu, submenu chevron and submenu side follow the trigger’s direction. Shortcuts keep their left-to-right order.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` `↓` | On the trigger, opens the menu and highlights the first item. |
| `↓` | Highlights the next item, wrapping at the end. |
| `↑` | Highlights the previous item, wrapping at the start. |
| `Home` | Highlights the first item. |
| `End` | Highlights the last item. |
| `Enter` `Space` | Runs the highlighted item. Checkbox and radio items toggle and keep the menu open. |
| `→` | Opens the highlighted submenu and moves into it. ← in right-to-left layouts. |
| `←` | Closes the current submenu and returns to its trigger. → in right-to-left layouts. |
| `Esc` | Closes the current menu and returns focus to its trigger. In a submenu, only that submenu closes. |
| `A–Z` | Highlights the next item starting with that letter. |

## Accessibility

- The trigger is announced as a menu button, and focus returns to it when the menu closes.
- Give icon-only triggers an `aria-label`, like the row actions example does.
- `<DropdownMenuShortcut />` is a visual label only. Bind the keys yourself.
- With reduced motion on, the menu fades without scaling and the item blink is skipped.

## API reference

Built on the Base UI menu. Every part accepts the props of the primitive it wraps.

### DropdownMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `showSafeArea` | `boolean` | `false` | Draws the submenu safe area while the menu is open. For debugging and demos. |
| `onOpenChange` | `(open: boolean, details) => void` | – | details.reason says what caused the change. |
| `modal` | `boolean` | `true` | Locks page scroll and blocks outside clicks while open. |
| `loopFocus` | `boolean` | `true` | Wrap the arrow keys at either end. |
| `handle` | `DropdownMenuHandle<Payload>` | – | Connects detached triggers to this menu. |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – | Use the function form to read the opening trigger’s payload. |
| `disabled` | `boolean` | `false` |  |

### DropdownMenuTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `openOnHover` | `boolean` | `false` |  |
| `delay` | `number` | `100` | Milliseconds before a hover opens the menu. |
| `closeDelay` | `number` | `0` | Milliseconds before a hover-opened menu closes. |
| `handle` | `DropdownMenuHandle<Payload>` | – |  |
| `payload` | `Payload` | – | Passed to the menu when this trigger opens it. |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-trigger"` | Target the trigger in CSS. |
| `data-popup-open` | Present while its menu is open. |
| `data-pressed` | Present while the trigger is pressed. |
| `data-disabled` | Present when the trigger is disabled. |

### DropdownMenuContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"` |  |
| `align` | `"start" \| "center" \| "end"` | `"start"` |  |
| `sideOffset` | `number` | `4` |  |
| `alignOffset` | `number` | `0` |  |
| `collisionPadding` | `number \| Rect` | `8` | Space kept between the menu and the edge of the viewport. |
| `anchor` | `Element \| RefObject \| VirtualElement` | – | Position against another element instead of the trigger. |
| `sticky` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-content"` | Target the menu in CSS. |
| `data-open` | Present while the menu is open. |
| `data-starting-style` | Present while the menu animates in. |
| `data-ending-style` | Present while the menu animates out. |
| `data-side` | The side the menu settled on after collision handling. |
| `data-align` | The alignment it settled on. |
| `data-chosen` | Present after an item is clicked, so the menu waits for the item’s confirmation blink before closing. |
| `--anchor-width` | The trigger’s width. The menu is at least this wide. |
| `--available-height` | Room left in the viewport. Long menus scroll within it. |
| `--transform-origin` | Where the scale animation grows from, next to the trigger. |

### DropdownMenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "destructive"` | `"default"` |  |
| `inset` | `boolean` | `false` | Indents the item to line up with checkbox items. |
| `closeOnClick` | `boolean` | `true` |  |
| `onClick` | `(event) => void` | – |  |
| `label` | `string` | – | Text used for type-ahead when children aren’t plain text. |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` | Render a link with render={<a href="…" />}. |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-item"` | Target items in CSS. |
| `data-variant` | The current variant. |
| `data-highlighted` | Present while the item is highlighted by pointer or keyboard. |
| `data-disabled` | Present when the item is disabled. |
| `data-chosen` | Present on the item that was just clicked, while it blinks. |
| `data-inset` | Present when inset is set. |

### DropdownMenuCheckboxItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – |  |
| `defaultChecked` | `boolean` | `false` |  |
| `onCheckedChange` | `(checked: boolean, details) => void` | – |  |
| `closeOnClick` | `boolean` | `false` |  |
| `inset` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-checkbox-item"` | Target checkbox items in CSS. |
| `data-checked` | Present when checked. |
| `data-unchecked` | Present when not checked. |
| `data-highlighted` | Present while the item is highlighted by pointer or keyboard. |
| `data-disabled` | Present when the item is disabled. |
| `data-chosen` | Present on the item that was just clicked, while it blinks. |
| `data-inset` | Present when inset is set. |

### DropdownMenuRadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` | – |  |
| `defaultValue` | `Value` | – |  |
| `onValueChange` | `(value: Value, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |

### DropdownMenuRadioItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` | – |  |
| `closeOnClick` | `boolean` | `false` |  |
| `inset` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-radio-item"` | Target radio items in CSS. |
| `data-checked` | Present on the selected item. |
| `data-unchecked` | Present on the other items. |
| `data-highlighted` | Present while the item is highlighted by pointer or keyboard. |
| `data-disabled` | Present when the item is disabled. |
| `data-chosen` | Present on the item that was just clicked, while it blinks. |
| `data-inset` | Present when inset is set. |

### DropdownMenuGroup

Groups related items. A `<DropdownMenuLabel />` inside it becomes the group’s accessible name.

### DropdownMenuLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

### DropdownMenuSeparator

A divider between groups, announced as a separator.

### DropdownMenuShortcut

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `dir` | `"ltr" \| "rtl"` | `"ltr"` | Shortcuts keep their key order in right-to-left menus. |

### DropdownMenuSub

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `closeParentOnEsc` | `boolean` | `false` | Close the whole menu, not just this submenu, on Escape. |

### DropdownMenuSubTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inset` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `delay` | `number` | `100` | Milliseconds before hovering opens the submenu. |
| `closeDelay` | `number` | `0` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-sub-trigger"` | Target submenu triggers in CSS. |
| `data-popup-open` | Present while its submenu is open. |
| `data-highlighted` | Present while highlighted. |

### DropdownMenuSubContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sideOffset` | `number` | `0` |  |
| `alignOffset` | `number` | `-4` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="dropdown-menu-sub-content"` | Target submenus in CSS. |
| `data-open` | Present while the menu is open. |
| `data-starting-style` | Present while the menu animates in. |
| `data-ending-style` | Present while the menu animates out. |
| `data-side` | The side the menu settled on after collision handling. |
| `data-align` | The alignment it settled on. |
| `data-chosen` | Present after an item is clicked, so the menu waits for the item’s confirmation blink before closing. |
| `--available-height` | Room left in the viewport. Long menus scroll within it. |
| `--transform-origin` | Where the scale animation grows from, next to the trigger. |

---

# Empty

> A placeholder for screens with nothing to show yet, with an icon, a message and the next action.

Docs: https://hextaui.com/docs/empty
Markdown: https://hextaui.com/docs/empty.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/empty.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/empty.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty"
```

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia variant="stack">
      <IconFolder />
    </EmptyMedia>
    <EmptyTitle>No projects yet</EmptyTitle>
    <EmptyDescription>Create a project to get started.</EmptyDescription>
  </EmptyHeader>
  <EmptyContent>
    <Button>Create project</Button>
  </EmptyContent>
</Empty>
```

## Composition

```text
Empty
├── EmptyHeader
│   ├── EmptyMedia
│   ├── EmptyTitle
│   └── EmptyDescription
└── EmptyContent
```

## Examples

### Entrance

When an empty state replaces content, its parts fade up one after another: media, title, description, then actions. Dismiss the notifications to see it. Under reduced motion it just appears. Set `animated={false}` for empty states that are there from the first paint.

### Outline

`variant="outline"` draws a dashed hairline border, the usual way to mark a drop zone or an area waiting for content.

### Muted

`variant="muted"` sits on a soft fill. The icon tile switches to a raised white surface so it still stands out.

### Small

`size="sm"` tightens the padding, gaps, icon tile and title for sidebars, popovers and narrow panels.

### Avatar

The default `EmptyMedia` variant only centers its content, so any avatar, badge or illustration fits.

### Avatar group

Show who could be here, for invites and shared spaces.

### Image

Give images explicit dimensions so the layout doesn’t shift while they load.

### No search results

Swap the results for an empty state when filters match nothing, and offer a way out. A visually hidden `role="status"` announces the count, so screen reader users hear the change without the whole list being read.

### In a card

Use `size="sm"` with the muted variant to fill a card that has no data yet.

### In a table

Put it in a single cell that spans every column with `colSpan`, so the header stays aligned.

### In a popover

A compact empty state for menus and notification panels.

### In a command list

`<CommandEmpty />` passes the current search to a function child, so the message can quote it.

### Heading level

The title is a `<div>` so it never breaks your page outline. Render it as the heading level that fits, and label the region with it.

### Long content

Unbroken names and long addresses wrap inside the container, and long button labels truncate.

### Right to left

Everything is centered and uses logical properties, so it reads naturally in right-to-left layouts.

## Accessibility

- `<EmptyTitle />` renders a `<div>`. Pass `render={<h2 />}` (or the level that fits) when the empty state is a section of the page.
- `<EmptyMedia variant="icon" />` is hidden from assistive tech because the title already says what it means. Images in the default variant stay exposed, so give them an `alt` or `alt=""`.
- When results disappear after a search or filter, announce the change with a short `role="status"` message next to the list. Don’t make the whole empty state a live region, since its buttons and links would be read every time.

## API reference

Every part renders a plain element, accepts its attributes and supports the `render` prop to swap it.

### Empty

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "muted"` | `"default"` |  |
| `size` | `"default" \| "sm"` | `"default"` | sm tightens padding, gaps, the icon tile and the title. |
| `animated` | `boolean` | `true` | Fade the parts up in sequence when the empty state mounts. Skipped under reduced motion. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="empty"` | Target the root in CSS. |
| `data-variant` | The current variant. |
| `data-size` | The current size. |
| `data-animated` | Present when the entrance animation is on. |
| `--empty-padding` | Padding on every side. Set by size. |
| `--empty-gap` | Space between the header and content. Set by size. |

### EmptyHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="empty-header"` | Target the header in CSS. |

### EmptyMedia

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "icon" \| "stack"` | `"default"` | icon puts an icon in a muted tile. stack raises the tile over two fanned cards that spread when the empty state is hovered. Both hide the media from assistive tech. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="empty-icon"` | Target the media in CSS. Matches shadcn. |
| `data-variant` | The current variant. |

### EmptyTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` | Render a heading, such as render={<h2 />}. |

| Attribute | Description |
| --- | --- |
| `data-slot="empty-title"` | Target the title in CSS. |

### EmptyDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` | Plain links inside are underlined. Components rendered as links keep their own style. |

| Attribute | Description |
| --- | --- |
| `data-slot="empty-description"` | Target the description in CSS. |

### EmptyContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="empty-content"` | Target the actions area in CSS. |

---

# Field

> Labels, descriptions and errors wired to their control, with validation states and layouts for forms.

Docs: https://hextaui.com/docs/field
Markdown: https://hextaui.com/docs/field.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/field.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/field.tsx`, `components/ui/input.tsx`, `components/ui/number-flow.tsx`, `components/ui/separator.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Field,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
} from "@/components/ui/field"
```

```tsx
<FieldGroup indicator="optional">
  <Field>
    <FieldLabel>Email</FieldLabel>
    <Input type="email" required />
    <FieldDescription>We’ll never share it.</FieldDescription>
    <FieldError />
  </Field>
</FieldGroup>
```

Put any HextaUI control inside a `<Field />` and it’s labelled, described and validated automatically. There’s no need to wire up `id`, `htmlFor` or `aria-describedby` by hand.

## Composition

### Single field

One control with its label, help text and validation.

```text
Field
├── FieldLabel
├── Input / Textarea / Select / …
├── FieldDescription
├── FieldError
├── FieldCounter
└── FieldStatus
```

### Horizontal field

A switch or checkbox with its text beside it.

```text
Field
├── Switch / Checkbox
└── FieldContent
    ├── FieldLabel
    └── FieldDescription
```

### Choice card

A label that wraps a whole field, so the card is the click target.

```text
FieldLabel
└── Field
    ├── Checkbox / RadioGroupItem
    └── FieldContent
        ├── FieldTitle
        └── FieldDescription
```

### Grouped fields

Related fields, spaced evenly.

```text
FieldGroup
├── Field
├── FieldSeparator
└── Field
```

### Fieldsets

A titled group of fields, or a radio or checkbox group with an item per option.

```text
FieldSet
├── FieldLegend
├── FieldDescription
└── FieldGroup
    └── Field

FieldSet
├── FieldLegend
└── FieldItem
    ├── RadioGroupItem / Checkbox
    └── FieldLabel
```

## Examples

### Input

A label, a control and a description. Clicking the label focuses the input, and screen readers read the description after the label.

### Validation

Native constraints like `required` and `minLength` are checked on blur. Give each `<FieldError />` a `match` to word the message per problem. An empty required field is only flagged after it has been edited, so tabbing past it doesn’t shout.

### Custom validation

Pass `validate` to check anything, including async lookups. Return a message to fail or nothing to pass. With `validationMode="onChange"` and `validationDebounceTime`, it runs while typing without firing on every key. Try “ada”.

### Required and optional

Set `indicator` on a `FieldGroup`, `FieldSet` or `Field` and every label inside marks itself from its control's `required` attribute. `"optional"` tags the fields people can skip, which reads calmer when most fields are required. `"required"` adds an asterisk. The mark is hidden from screen readers because the control already announces it.

### Status

`<FieldStatus />` draws a check once an edited field passes validation, and shows an alert icon while it fails. It follows the field's `validationMode`, so it never judges a field before validation has run.

### Character count

`<FieldCounter />` finds the text control in its field and counts against its `maxLength`. It only listens, so typing is never slowed or changed.

### Errors from a form library or server

Pass `invalid` to the field and an `errors` array to `<FieldError />`. It takes the `{ message }` shape React Hook Form and most schema libraries return. Duplicates are dropped, and several messages become a list. When the messages change, the new ones fade in and the height eases to fit, so nothing below jumps. Submit empty, then fix one rule at a time.

### Checkboxes

Use `orientation="horizontal"` to put the checkbox beside its label. Inside a `<FieldSet />`, the legend names the whole group.

### Choice cards

Wrap a whole field in `<FieldLabel />` to make the card the click target. Use `<FieldTitle />` inside, since labels can’t nest. The card tints when checked and shows the focus ring when its checkbox is focused.

### Fieldset

`<FieldSet />` groups related fields under a `<FieldLegend />`, which becomes the group’s accessible name. Lay fields out side by side with a plain grid.

### Responsive

`orientation="responsive"` stacks the label and control in narrow spaces and puts them side by side once the surrounding `<FieldGroup />` is wide enough. It responds to the group’s width, not the window’s.

### Disabled

Disabling a `<FieldSet />` disables every field and control inside it. Pass `disabled` to a single `<Field />` to disable just that one.

### Long content

Labels, descriptions and errors wrap inside narrow forms, including unbroken strings, and never push the layout wider.

### Right to left

Text, checkbox placement and error lists follow the reading direction.

## Accessibility

- The label, description and visible errors are linked to the control for you, so screen readers announce all three when it’s focused.
- Invalid controls get `aria-invalid`, which also draws their error ring.
- Errors are not live regions. They’re read when the control is focused, so validating on change doesn’t interrupt typing. On submit, move focus to the first invalid field.
- Errors grow and fade in place instead of pushing content down. With reduced motion on, they appear without animating.

## API reference

Built on the Base UI field and fieldset. Every part accepts the props of the element or primitive it renders.

### Field

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` |  |
| `indicator` | `"required" \| "optional" \| null` | – | Mark the label from the control's required attribute. Inherited from FieldGroup or FieldSet. |
| `name` | `string` | – | Identifies the field when the form is submitted. |
| `validate` | `(value, formValues) => string \| string[] \| null \| Promise<…>` | – | Return one or more messages to fail, or nothing to pass. Async is supported. |
| `validationMode` | `"onSubmit" \| "onBlur" \| "onChange"` | `"onSubmit"` |  |
| `validationDebounceTime` | `number` | `0` | Milliseconds to wait between onChange validations. |
| `invalid` | `boolean` | – | Set it from a form library or server response. |
| `disabled` | `boolean` | `false` |  |
| `dirty` | `boolean` | – |  |
| `touched` | `boolean` | – |  |
| `actionsRef` | `RefObject<{ validate: () => void }>` | – | Validate the field imperatively. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field"` | Target fields in CSS. |
| `data-orientation` | The current orientation. |
| `data-disabled` | Present when the field is disabled. |
| `data-valid` | Present when the field is valid. |
| `data-invalid` | Present when the field is invalid. |
| `data-dirty` | Present once the value has changed from its initial value. |
| `data-touched` | Present once the control has been focused and left. |
| `data-filled` | Present when the control has a value. |
| `data-focused` | Present while the control has focus. |

### FieldLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `nativeLabel` | `boolean` | `true` | Set false when render swaps the label for a non-label element. |
| `optionalText` | `ReactNode` | `"Optional"` | Text shown with indicator="optional". |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<label>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field-label"` | Target labels in CSS. Outside a field it renders a plain label, which is how choice cards work. |
| `data-disabled` | Present when the field is disabled. |
| `data-valid` | Present when the field is valid. |
| `data-invalid` | Present when the field is invalid. |
| `data-dirty` | Present once the value has changed from its initial value. |
| `data-touched` | Present once the control has been focused and left. |
| `data-filled` | Present when the control has a value. |
| `data-focused` | Present while the control has focus. |

### FieldStatus

An icon that reflects the field's validity. It's decorative, since the error message carries the meaning.

| Attribute | Description |
| --- | --- |
| `data-slot="field-status"` | Target the status icon in CSS. |

### FieldCounter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `threshold` | `number` | `10% of maxLength, at most 20` |  |
| `announcement` | `(remaining: number) => string` | – | Message for screen readers when the count crosses the threshold or hits the limit. |

| Attribute | Description |
| --- | --- |
| `data-slot="field-counter"` | Target the counter in CSS. |
| `data-state="near" \| "limit"` | Present within the threshold, and at the limit. |

### FieldDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field-description"` | Target descriptions in CSS. |
| `data-disabled` | Present when the field is disabled. |
| `data-valid` | Present when the field is valid. |
| `data-invalid` | Present when the field is invalid. |
| `data-dirty` | Present once the value has changed from its initial value. |
| `data-touched` | Present once the control has been focused and left. |
| `data-filled` | Present when the control has a value. |
| `data-focused` | Present while the control has focus. |

### FieldError

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `match` | `boolean \| "valueMissing" \| "typeMismatch" \| "tooShort" \| "tooLong" \| "patternMismatch" \| "rangeOverflow" \| "rangeUnderflow" \| "stepMismatch" \| "badInput" \| "customError" \| "valid"` | – | Show only for this validity problem. true always shows it. |
| `errors` | `Array<{ message?: string } \| undefined>` | – | Errors from a form library or server. Shown when the list has a message. |
| `children` | `ReactNode` | – | Defaults to the validation message. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field-error"` | Target errors in CSS. |
| `data-starting-style` | Present while the error grows in. |
| `data-ending-style` | Present while the error collapses. |
| `data-disabled` | Present when the field is disabled. |
| `data-valid` | Present when the field is valid. |
| `data-invalid` | Present when the field is invalid. |
| `data-dirty` | Present once the value has changed from its initial value. |
| `data-touched` | Present once the control has been focused and left. |
| `data-filled` | Present when the control has a value. |
| `data-focused` | Present while the control has focus. |

### FieldContent

Stacks a label, description and error beside a control in a horizontal field.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

### FieldTitle

A label-styled title for content inside a `<FieldLabel />`, such as choice cards.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

### FieldGroup

Spaces fields apart and is the container that responsive fields measure.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indicator` | `"required" \| "optional" \| null` | – | Applies to every field inside. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

### FieldSet

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `indicator` | `"required" \| "optional" \| null` | – | Applies to every field inside. |
| `disabled` | `boolean` | `false` | Disables every field inside. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<fieldset>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field-set"` | Target fieldsets in CSS. |
| `data-disabled` | Present when the fieldset is disabled. |

### FieldLegend

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"legend" \| "label"` | `"legend"` | label matches the size of a field label. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field-legend"` | Target legends in CSS. |
| `data-variant` | The current variant. |

### FieldSeparator

A `<Separator />` spaced for forms, and accepts all of its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | – | Optional text shown in the middle of the line. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Where the text sits along the line. |
| `decorative` | `boolean` | `false` | Hide a plain line from screen readers when it is only visual. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="field-separator"` | Target field separators in CSS. |
| `data-content` | Present when the separator has text. |
| `data-slot="separator-label"` | The element that wraps the text. |

### FieldItem

Wraps one checkbox or radio and its label inside a group, so each item can be disabled on its own.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

### FieldValidity

Renders anything from the field’s validity state, for example a strength meter or a character counter.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(state: { validity, errors, error, value }) => ReactNode` | – |  |

---

# Hover card

> A preview card that opens when a link is hovered or focused, for content sighted users can glance at.

Docs: https://hextaui.com/docs/hover-card
Markdown: https://hextaui.com/docs/hover-card.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/hover-card.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react cn
```

Copy `components/ui/hover-card.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@/components/ui/hover-card"
```

```tsx
<HoverCard>
  <HoverCardTrigger href="/profile" render={<Button variant="link" nativeButton={false} render={<a />} />}>
    @hextaui
  </HoverCardTrigger>
  <HoverCardContent>
    Components built on shadcn/ui.
  </HoverCardContent>
</HoverCard>
```

A hover card is a preview, not a menu or a dialog. The trigger stays a normal link, so everything in the card must also be on the page it links to.

## Composition

```text
HoverCard
├── HoverCardTrigger
└── HoverCardContent
```

## Examples

### Side

Set `side` and `align` on `<HoverCardContent />`. Logical sides like `inline-end` follow the reading direction, and the card flips or shifts when it would leave the screen.

### Delay

`delay` and `closeDelay` on the trigger set how long the pointer must rest before the card opens and how long it lingers after leaving. The 600ms default stops cards from flashing open as the pointer crosses a page.

### Inline link

Use `render` to make the trigger any link, including one inside a sentence. When a link wraps onto two lines, the card anchors to the line you hovered.

### Interactive content

Move the pointer from the link into the card and it stays open, so links and buttons inside can be clicked. The path between them is forgiving, so a diagonal move doesn’t close it.

### Shared card

One card serves many links. Create a handle with `createHoverCardHandle`, give each trigger a `payload`, and read it in the card. Moving between names glides the card to the new link instead of closing and reopening it. The old content slides out the way you moved, the new content slides in, and the height eases between the two.

### Arrow

`arrow` adds a pointer that joins the card's border without a seam. The side offset grows to make room for it, and it follows the card when it flips.

### Loading content

Start fetching in `onOpenChange` and show a skeleton until the data arrives. When the content changes, the card eases to its new height instead of jumping.

### Controlled

Pass `open` and `onOpenChange`. The second argument says why it changed, such as `trigger-hover`, `trigger-focus` or `escape-key`.

### Long content

Unbroken text wraps inside the card, and a card taller than the space beside the trigger scrolls instead of leaving the screen.

### Right to left

The card reads the trigger’s direction, so logical sides and alignment flip and the scale animation grows from the correct corner.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Focusing the trigger opens the card after the same delay as hover. Moving focus on closes it. |
| `Enter` | Follows the link, like any other link. |
| `Esc` | Closes the card. |

## Accessibility

- The card is a visual extra for sighted mouse and keyboard users. Screen readers only hear the link, so they aren’t forced through a preview on every link they pass.
- Nothing opens on touch screens, where there is no hover. A tap follows the link, which is why the destination has to hold the same information.
- Focus never moves into the card. If it needs controls that must be reachable from the keyboard, use a popover instead.
- With reduced motion on, the card fades without scaling, and a shared card jumps between links instead of gliding.

## API reference

Built on the Base UI preview card. Every part accepts the props of the primitive it wraps.

### HoverCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – | details.reason is trigger-hover, trigger-focus, trigger-press, outside-press, escape-key, imperative-action or none. |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the open or close animation ends. |
| `handle` | `HoverCardHandle<Payload>` | – | Connects triggers rendered outside the root. |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – | Use the function form to read the payload of the trigger that opened the card. |
| `actionsRef` | `RefObject<{ close, unmount }>` | – |  |

### HoverCardTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string` | – |  |
| `delay` | `number` | `600` | Milliseconds before hover or focus opens the card. |
| `closeDelay` | `number` | `300` | Milliseconds the card stays open after leaving. |
| `handle` | `HoverCardHandle<Payload>` | – |  |
| `payload` | `Payload` | – | Passed to the card when this trigger opens it. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<a>` | Render your own link, such as <Button variant="link" /> or a router link. |

| Attribute | Description |
| --- | --- |
| `data-slot="hover-card-trigger"` | Target the trigger in CSS. |
| `data-popup-open` | Present while this trigger’s card is open. |

### HoverCardContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"` |  |
| `align` | `"start" \| "center" \| "end"` | `"center"` |  |
| `arrow` | `boolean` | `false` | Show a pointer toward the trigger. |
| `sideOffset` | `number \| OffsetFunction` | `6, or 10 with arrow` |  |
| `alignOffset` | `number \| OffsetFunction` | `0` |  |
| `collisionPadding` | `number \| Rect` | `8` | Space kept between the card and the viewport edge. |
| `collisionAvoidance` | `CollisionAvoidance` | – | Whether the card flips, shifts or does nothing on collision. |
| `sticky` | `boolean` | `false` |  |
| `anchor` | `Element \| RefObject \| VirtualElement` | – | Position against something other than the trigger. |
| `positionMethod` | `"absolute" \| "fixed"` | `"absolute"` |  |
| `disableAnchorTracking` | `boolean` | `false` |  |
| `portalProps` | `HoverCardPortalProps` | – | Props for the portal, such as container. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="hover-card-content"` | Target the card in CSS. |
| `data-open` | Present while the card is open. |
| `data-starting-style` | Present while the card animates in. |
| `data-ending-style` | Present while the card animates out. |
| `data-instant` | focus when keyboard focus opened the card, dismiss when Escape or an outside press closed it. The exit animation is skipped while it’s set. |
| `data-side` | The side the card settled on after collisions. |
| `data-align` | The alignment it settled on. |
| `--transform-origin` | Where the scale animation grows from, next to the trigger. |
| `--available-width` | Room left beside the trigger. The card never grows past it. |
| `--available-height` | Room left above or below. Taller content scrolls. |

| Positioner attribute | Description |
| --- | --- |
| `data-slot="hover-card-positioner"` | The element that moves. It glides when a shared card switches links. |
| `data-anchor-hidden` | Present when the trigger scrolls out of view. |

| Inner parts | Description |
| --- | --- |
| `data-slot="hover-card-viewport"` | Wraps the content. Carries data-activation-direction while a shared card switches links. |
| `data-slot="hover-card-body"` | Your content. Its height eases when it changes. |
| `data-slot="hover-card-arrow"` | The pointer, with data-side for its edge. |
| `--popup-height` | Set on the card while it resizes between links. |

### HoverCardPortal

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `container` | `HTMLElement \| ShadowRoot \| RefObject \| null` | `document.body` |  |
| `keepMounted` | `boolean` | `false` |  |

### createHoverCardHandle

Returns a handle for detached triggers. Its `open(triggerId)` and `close()` methods control the card from event handlers, and `isOpen` reads its state. Pass a type argument to type the payload.

---

# Input

> A text input with three sizes, invalid and read-only states, native validation styling and a 16px touch font so phones never zoom in.

Docs: https://hextaui.com/docs/input
Markdown: https://hextaui.com/docs/input.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/input.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/input.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Input } from "@/components/ui/input"
```

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

## Examples

### Sizes

`sm`, `default` and `lg` match the button heights, so an input and a button of the same size line up in a row.

### With a description

Point `aria-describedby` at the helper text so screen readers read it after the label.

### Invalid

`aria-invalid` turns the edge and the focus ring red. Link the message with `aria-describedby` so it is announced, not just colored.

### Native validation

Fields with `required`, `type="email"` or `pattern` only turn red after someone has typed in them or tried to submit, never on first render. A submit that finds a field invalid shakes it once, so the eye lands on what needs fixing. It never shakes while you type or tab around. Submit the empty form to see it.

### Disabled

A disabled input can’t be focused, edited or submitted with the form.

### Read only

`readOnly` keeps the value focusable, selectable and submitted, with a muted surface so it doesn’t look editable. Prefer it over `disabled` for values people need to copy.

### File

`type="file"` gets the same frame, with the browser’s button restyled as plain text.

### Input types

Password, number, search, date and time share one height and frame. In dark mode, the browser’s pickers and spinners switch to dark too.

### Controlled

`onValueChange` hands you the string directly, so there’s no `event.target.value` to unwrap. `onChange` still works too.

### With a button

Side by side with a gap, or joined into one control inside a `<ButtonGroup />`, where the input takes the remaining width.

### Grid

Inputs fill their container, so place them in a grid. Give grid cells `min-w-0` so long values can’t stretch a column.

### Long content

Long values scroll inside the field and long placeholders are cut off, without widening the layout.

### Right to left

Text, caret and padding follow the direction. Use `dir="auto"` on fields that hold left-to-right values, like an email address in an Arabic form.

## Accessibility

- Every input needs a name. Use a `<label>` with `htmlFor`, or `aria-label` when there’s no visible label. A placeholder is not a label.
- Connect helper and error text with `aria-describedby`, and set `aria-invalid` only once there is an error to show.
- On touch screens the text is at least 16px, so iOS Safari doesn’t zoom the page when the input is focused.
- Inside a Base UI `Field`, the label, description, error and validity are wired up for you.

## API reference

Built on the Base UI input. It accepts every native input attribute.

### Input

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Height and padding, matched to the buttons. |
| `htmlSize` | `number` | – | The native size attribute, renamed because size is the variant. |
| `value` | `string \| number \| string[]` | – |  |
| `defaultValue` | `string \| number \| string[]` | – |  |
| `onValueChange` | `(value: string, details) => void` | – | Called with the new value on every change. |
| `type` | `string` | `"text"` |  |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |
| `aria-invalid` | `boolean` | – | Shows the invalid edge and focus ring. |
| `className` | `string \| (state) => string` | – |  |
| `shake` | `boolean` | `true` | Shake once when a form submit finds this input invalid. Works with native validation, Base UI Field and libraries that set aria-invalid. Skipped under reduced motion. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<input>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input"` | Target the input in CSS. |
| `data-size` | The current size. |
| `data-shake` | Present while the input shakes after a failed submit. |
| `data-disabled` | Present when the input is disabled. |
| `data-invalid` | Present when the surrounding Field is invalid. Styled like aria-invalid. |
| `data-valid` | Present when the surrounding Field is valid. |
| `data-touched` | Present after the input lost focus once, inside a Field. |
| `data-dirty` | Present once the value changed, inside a Field. |
| `data-filled` | Present when the input has a value, inside a Field. |
| `data-focused` | Present while focused, inside a Field. |

### inputVariants

The class names behind the input, for styling another element to match, such as a native `<select>` or `<textarea>`. Call it with `{ size }`.

### InputCount

The character count behind `<InputGroupCount />` and `<FieldCounter />`. Use those parts, which read the field for you. Reach for this one only when you track the length yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | – | Required. |
| `maxLength` | `number \| null` | – |  |
| `threshold` | `number` | `10% of maxLength, at most 20` |  |
| `announcement` | `(remaining: number) => string` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-count"` | Target the count in CSS. |
| `data-state="near" \| "limit"` | Present within the threshold, and at the limit. |

---

# Input group

> An input with icons, text, buttons or a keyboard hint attached, sharing one border and focus ring.

Docs: https://hextaui.com/docs/input-group
Markdown: https://hextaui.com/docs/input-group.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/input-group.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/input-group.tsx`, `components/ui/input.tsx`, `components/ui/button.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupClear,
  InputGroupCount,
  InputGroupInput,
  InputGroupPasswordToggle,
  InputGroupText,
  InputGroupTextarea,
} from "@/components/ui/input-group"
```

```tsx
<InputGroup>
  <InputGroupInput placeholder="Search…" aria-label="Search" />
  <InputGroupAddon>
    <IconSearch />
  </InputGroupAddon>
  <InputGroupAddon align="inline-end">
    <InputGroupClear />
  </InputGroupAddon>
</InputGroup>
```

Put `<InputGroupInput />` or `<InputGroupTextarea />` first and the addons after it. Addons place themselves with `align`, so the field comes first in the tab order and for screen readers.

The group tracks its field, so the smart parts need no wiring. `<InputGroupClear />`, `<InputGroupPasswordToggle />` and `<InputGroupCount />` read the value, `type` and `maxLength` from the field, whether it's controlled or not.

## Composition

```text
InputGroup
├── InputGroupAddon
│   ├── InputGroupText
│   ├── InputGroupButton
│   ├── InputGroupClear
│   ├── InputGroupCount
│   └── InputGroupPasswordToggle
└── InputGroupInput / InputGroupTextarea
```

## Examples

### Icon

Icons sit inside the border on either side. Clicking an icon focuses the input, so the whole group feels like one field.

### Clear

`<InputGroupClear />` fades in once there's a value. It clears through the browser's edit history, so Cmd+Z brings the text back, and it fires your `onChange`. Escape clears too. A second Escape is left for the dialog or popover around it.

### Character count

`<InputGroupCount />` counts against the field's `maxLength`. Only the digits that change roll. The count darkens near the limit and turns red at it, and a typed key past the limit nudges it. Screen readers hear a message when the field gets close to the limit and when it reaches it, never on every key.

### Text

Use `<InputGroupText />` for units, currencies and URL parts. The input's padding shrinks next to an addon so the text reads as one value.

### Button

`<InputGroupButton />` is a ghost button sized to fit inside the field. Its corners are concentric with the group's, and it gets its own focus ring.

### Keyboard hint

A plain `<kbd>` inside an addon is styled as a key cap. It's a visual hint only, so bind the shortcut yourself.

### Textarea

`<InputGroupTextarea />` grows with its content up to 16rem, then scrolls. The height eases between lines instead of jumping. A `block-end` addon becomes a toolbar under it, and buttons at its edges get the same inset as the corner they sit in.

### Header

A `block-start` addon sits above the field. Add `separator` to draw a hairline between them.

### Password

`<InputGroupPasswordToggle />` switches a `type="password"` field to text and back. The caret and selection stay where they were, a mouse click keeps focus in the field, and the password is hidden again when the form submits. Control it with `revealed`.

### Sizes

`size` on the group sets the height and passes down to the input, matching `<Input />` sizes. Buttons keep concentric corners at every size.

### Invalid

Set `aria-invalid` on the input and the whole group turns red, including its focus ring. Link the message with `aria-describedby`.

### Disabled

A disabled input dims the whole group and shows a not-allowed cursor over it. Disable addon buttons too, since they stay usable otherwise.

### Loading

Inline addons ease to their new width when their content changes, so the field never jumps as a spinner turns into a result count. The spinner only turns when motion is allowed, and `role="status"` announces the text.

### Dropdown

Render an `<InputGroupButton />` as a dropdown trigger to scope the input.

### Long content

Long values scroll inside the input instead of stretching the group. Wrap long addon text in a truncating span with a max width.

### Right to left

Addons, padding and corner radii use logical sides, so inline-start lands on the right.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves from the field to each addon button, in source order. |
| `Shift` `Tab` | Moves back through the buttons and the field. |
| `Escape` | With an InputGroupClear, clears the field. When it's already empty, Escape passes through. |

## Accessibility

- Every field needs a name. Use a visible label, a Field, or `aria-label`. Icons and addon text aren't part of the field's name.
- Give icon-only buttons an `aria-label`.
- When addon text carries meaning, like a currency or a domain, add it to the label or reference it with `aria-describedby`.
- `<InputGroupClear />` is skipped in the tab order because Escape does the same thing. The password toggle stays tabbable and keeps the same name, with `aria-pressed` reporting its state.
- When a submit finds the field invalid, the group shakes once. With reduced motion the red border is the only cue.
- On touch screens the field text is at least 16px so phones don't zoom in when it's focused.

## API reference

`<InputGroupInput />` and `<InputGroupTextarea />` accept the props of the elements they render. The other parts accept their element's attributes.

### InputGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Height of the group, passed down to the input. |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group"` | Target the group in CSS. Renders role="group". |
| `data-size` | The current size. |
| `data-filled` | Present while the field has a value. |
| `data-shake` | Present while the group shakes after a failed submit. |
| `data-disabled` | Set it yourself to dim the group when only the addons are disabled. |
| `--input-group-radius` | Corner radius of the group. Buttons and key caps derive their radius from it. |
| `--input-group-height` | Height of the group for the current size. |

### InputGroupInput

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | – | Inherited from the group. |
| `aria-invalid` | `boolean` | – |  |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-control"` | Marks the field. The group reads its focus, invalid, disabled and read-only states from it. |
| `data-invalid` | Present when a surrounding Field marks the value invalid. |
| `data-disabled` | Present when the field is disabled. |
| `data-focused` | Present while the field has focus. |
| `data-filled` | Present when the field has a value. |
| `data-dirty` | Present once the value differs from the initial one. |
| `data-touched` | Present once the field has been focused and left. |

### InputGroupTextarea

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoResize` | `boolean` | `true` | Grow with the content up to 16rem, easing between heights. |
| `shake` | `boolean` | `true` | Shake the group when a submit finds it invalid. |
| `rows` | `number` | – |  |
| `aria-invalid` | `boolean` | – |  |
| `disabled` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-control"` | Marks the field. The group reads its focus, invalid, disabled and read-only states from it. |
| `data-invalid` | Present when a surrounding Field marks the value invalid. |
| `data-disabled` | Present when the field is disabled. |
| `data-focused` | Present while the field has focus. |
| `data-filled` | Present when the field has a value. |
| `data-dirty` | Present once the value differs from the initial one. |
| `data-touched` | Present once the field has been focused and left. |

### InputGroupAddon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` |  |
| `separator` | `boolean` | `false` | Draw a hairline between a block addon and the field. |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-addon"` | Target addons in CSS. |
| `data-align` | The current alignment. |
| `data-separator` | Present when separator is set. |
| `--input-group-addon-inset` | Space between the group's edge and a button or key cap inside it. |

### InputGroupButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "secondary" \| "ghost" \| "destructive" \| "link"` | `"ghost"` |  |
| `size` | `"xs" \| "sm" \| "icon-xs" \| "icon-sm"` | `"xs"` |  |
| `type` | `string` | `"button"` |  |
| `feedback` | `boolean` | `false` | Every Button prop works, including the loading and success flow. |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-button"` | Target addon buttons in CSS. |
| `data-size` | The current size. |

### InputGroupClear

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onClear` | `() => void` | – | Called after the field is cleared. |
| `aria-label` | `string` | `"Clear"` |  |
| `children` | `ReactNode` | `<IconX />` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-clear"` | Target the clear button in CSS. |
| `data-visible` | Present while the field has a value and is editable. |

### InputGroupPasswordToggle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `revealed` | `boolean` | – | Controlled state. Leave unset to let it manage itself. |
| `onRevealedChange` | `(revealed: boolean) => void` | – |  |
| `aria-label` | `string` | `"Show password"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-password-toggle"` | Target the toggle in CSS. |
| `data-revealed` | Present while the password is shown. |

### InputGroupCount

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `threshold` | `number` | `10% of maxLength, at most 20` | Characters left when the count starts to stand out. |
| `announcement` | `(remaining: number) => string` | – | Message for screen readers when the count crosses the threshold or hits the limit. |

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-count"` | Target the count in CSS. |
| `data-state="near" \| "limit"` | Present within the threshold, and when no characters are left. |
| `data-bump` | Present briefly when a key is pressed at the limit. |

### InputGroupText

| Attribute | Description |
| --- | --- |
| `data-slot="input-group-text"` | Target addon text in CSS. |

---

# Input OTP

> One-time code slots that take typing, paste and SMS autofill, with an opt-in animation that cascades codes in and a status for verifying.

Docs: https://hextaui.com/docs/input-otp
Markdown: https://hextaui.com/docs/input-otp.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/input-otp.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/input-otp.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@/components/ui/input-otp"
```

```tsx
<label htmlFor="code">Verification code</label>
<InputOTP id="code" length={6}>
  <InputOTPGroup>
    <InputOTPSlot />
    <InputOTPSlot />
    <InputOTPSlot />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot />
    <InputOTPSlot />
    <InputOTPSlot />
  </InputOTPGroup>
</InputOTP>
```

Render one `<InputOTPSlot />` per character and set `length` to the same number. Slots find their position on their own, so there is no `index` prop to keep in sync.

## Composition

```text
InputOTP
├── InputOTPGroup
│   └── InputOTPSlot
├── InputOTPSeparator
└── InputOTPGroup
    └── InputOTPSlot
```

## Examples

### Joined

The default look. Each `<InputOTPGroup />` joins its slots into one strip with shared edges.

### Separate

`variant="separate"` gives every slot its own rounded box with a gap between them.

### Sizes

`sm`, `default` and `lg` match the input and button heights. On touch screens every size grows to at least 44px with a 16px font.

### Animated

`animated` is off by default. With it, typed characters rise in, deleted ones sink out while the rest slide over, and a whole code from autofill, paste or your own state cascades in slot by slot. Press Fill code to see the cascade.

### Status

`status` shows the result of checking the code. `loading` locks the slots and marks the field busy, `error` marks every slot invalid and `success` turns the edges green. Each one is announced. With `animated`, loading runs a wave, error shakes once and success pops the characters.

### Controlled

Pass `value` and `onValueChange`. The value is always the filtered code, never longer than `length`.

### Form

With a `name`, the code is submitted with the form. `autoSubmit` submits as soon as the last slot fills, so an autofilled code signs people in without another tap.

### With Field

Inside a `<Field />` the label, description and error are linked for you. Enter anything but 000000 to see the error.

### Invalid

`aria-invalid` on the root marks every slot. Link the message with `aria-describedby`.

### Letters and numbers

`validationType="alphanumeric"` accepts recovery and invite codes, and `normalizeValue` upper-cases them as they are typed or pasted.

### Masked

`mask` hides each character, for PINs. Turn autofill off with `autoComplete="off"` when the value is not a one-time code.

### Custom separator

Group the slots any way you like and pass your own icon to `<InputOTPSeparator />`.

### Disabled

A disabled field can’t be focused or edited.

### Right to left

Slots fill from the right and the arrow keys follow what you see. Give slots after the first a translated `aria-label`. Set `dir="ltr"` on the field to keep a code left to right in a right-to-left page.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus into the field, to the first empty slot, and out again. Only one slot is in the tab order. |
| `←` `→` | Moves to the previous or next slot, in visual order in right-to-left layouts. |
| `Home` `↑` | Moves to the first slot. |
| `End` `↓` | Moves to the slot after the last character. |
| `Backspace` | Deletes the character in the slot, or the one before it when the slot is empty. Later characters move back. |
| `Delete` | Deletes the character in the slot and keeps focus there. |
| `Ctrl` `Backspace` | Clears the whole code. ⌘ Backspace on macOS. |
| `Ctrl` `A` | Selects the whole code (⌘ A on macOS). Backspace or Delete then clears it and returns to the first slot, typing or pasting replaces it, and Ctrl C copies all of it. Any other key or a click ends the selection. |

## Accessibility

- Each slot is a real input. The first takes its name from your `<label>` or `aria-label`; the others are named "Character 2 of 6" and so on. Pass `aria-label` on a slot to translate it.
- The first slot has `autocomplete="one-time-code"`, so iOS and macOS offer codes from Messages and Mail, Android offers SMS codes, and password managers can fill it. A whole code that lands in one slot is spread across all of them. The animated cascade runs for every source, including codes you set from the WebOTP API.
- Whenever the code becomes empty while a slot has focus, such as after a wrong code is cleared, focus moves back to the first slot so the next attempt starts in the right place.
- When `status` is set, a hidden live region next to the field announces it. Change the words with `loadingLabel`, `successLabel` and `errorLabel`.
- With `animated`, characters are drawn on a layer hidden from screen readers while the inputs keep the real value. Under reduced motion, characters only fade and the status wave becomes a gentle pulse.

## API reference

Built on the Base UI OTP field. Every Base UI prop is passed through.

### InputOTP

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | – | Required. The number of slots; render the same number of InputOTPSlot parts. |
| `variant` | `"joined" \| "separate"` | `"joined"` |  |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `animated` | `boolean` | `false` | Animate characters in and out, cascade multi-character input and animate the status. |
| `status` | `"idle" \| "loading" \| "success" \| "error"` | – | The result of checking the code. Loading makes the slots read-only. |
| `loadingLabel` | `string` | `"Verifying code"` |  |
| `successLabel` | `string` | `"Code verified"` |  |
| `errorLabel` | `string` | `"Code is incorrect"` |  |
| `value` | `string` | – |  |
| `defaultValue` | `string` | – |  |
| `onValueChange` | `(value: string, details) => void` | – |  |
| `onValueComplete` | `(value: string, details) => void` | – | Called when the last slot fills. |
| `onValueInvalid` | `(value: string, details) => void` | – | Called when typed or pasted characters are rejected. |
| `validationType` | `"numeric" \| "alpha" \| "alphanumeric" \| "none"` | `"numeric"` |  |
| `normalizeValue` | `(value: string) => string` | – | Runs after filtering. Keep it idempotent. |
| `inputMode` | `string` | – | Defaults from validationType. |
| `autoComplete` | `string` | `"one-time-code"` |  |
| `autoSubmit` | `boolean` | `false` |  |
| `mask` | `boolean` | `false` |  |
| `aria-invalid` | `boolean` | – | Marks every slot invalid. |
| `name` | `string` | – |  |
| `form` | `string` | – |  |
| `id` | `string` | – | Goes on the first slot, so a label's htmlFor points at it. |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |
| `required` | `boolean` | `false` |  |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-otp"` | The root. |
| `data-variant="joined" \| "separate"` | The current variant. |
| `data-size` | The current size. |
| `data-status` | The status, when one is set. |
| `data-animated` | Present when animated is on. |
| `data-shake` | Present while the field shakes after the status turns to error. |
| `data-complete` | Present when every slot is filled. |
| `data-filled` | Present when any slot is filled. |
| `data-focused` | Present while a slot has focus. |
| `data-disabled` | Present when disabled. |
| `data-readonly` | Present when read-only, including while loading. |
| `data-required` | Present when required. |
| `data-invalid / data-valid / data-touched / data-dirty` | Field state, inside a Field. |
| `data-slot="input-otp-status"` | The hidden live region, a sibling of the root. |

### InputOTPGroup

A plain element that lays out a run of slots. In the joined variant its slots share edges.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-otp-group"` | Target the group in CSS. |

### InputOTPSlot

A box holding one input. `className` goes on the box; every other prop goes on the input.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Character N of M"` | Ignored on the first slot, which uses the label. |
| `className` | `string \| (state) => string` | – | The state has the slot's index, value, filled and the field state. |
| `placeholder` | `string` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-otp-slot"` | The box. |
| `data-filled` | Present when the slot has a character. |
| `data-status` | The root's status, when not idle. |
| `--input-otp-index` | The slot's position, used to stagger the status motion. |
| `data-slot="input-otp-input"` | The input inside, with Base UI's data-filled, data-focused, data-complete and field attributes. |
| `data-slot="input-otp-char"` | The drawn character when animated. |

### InputOTPSeparator

A separator with a minus icon. Pass children to use another icon.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="input-otp-separator"` | Target the separator in CSS. |

### inputOTPSlotVariants

The class names behind a slot and a group (`inputOTPGroupVariants`). Call them with `{ variant, size }`.

---

# Item

> A row of media, text and actions for lists, settings and pickers, with a grouped surface and a hover highlight that glides between rows.

Docs: https://hextaui.com/docs/item
Markdown: https://hextaui.com/docs/item.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/item.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/item.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Item,
  ItemActions,
  ItemChevron,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
} from "@/components/ui/item"
```

```tsx
<ItemGroup variant="grouped">
  <Item render={<a href="/settings/profile" />}>
    <ItemMedia variant="icon">
      <IconUserCircle />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>Profile</ItemTitle>
      <ItemDescription>Name, photo and handle</ItemDescription>
    </ItemContent>
    <ItemChevron />
  </Item>
</ItemGroup>
```

Give icon media a `tone` for colored tiles like iOS Settings, or leave it unset for a neutral tile. An item becomes interactive when it renders as a link, button or label through `render`. Only then does it get hover, press and focus styles, so static rows never pretend to be clickable.

## Composition

```text
ItemGroup
├── Item
│   ├── ItemHeader
│   ├── ItemMedia
│   ├── ItemContent
│   │   ├── ItemTitle
│   │   └── ItemDescription
│   ├── ItemActions
│   ├── ItemChevron
│   └── ItemFooter
└── ItemSeparator
```

## Examples

### Grouped

`variant="grouped"` puts items on one surface. Separators are drawn for you and inset to the text, the first and last rows own the outer corners, and the separators next to a hovered or focused row fade out.

### Hover highlight

Interactive items in a group share one highlight that glides to the row under the pointer and takes on its corners. It only follows a mouse or pen, never touch, and turn it off with `highlight={false}`. Image media corners are concentric with the row.

### Selectable

Render an item as a `<label>` around a Checkbox and the whole row toggles it. A checked control, or `aria-selected`, `aria-checked` or `aria-pressed` on the item, marks the row selected.

### Variants

`default` has no surface, `outline` draws a hairline and `muted` sits on a soft fill.

### Sizes

`size` scales padding, gap, corner radius and media together. A group tightens its gap to match.

### Avatar

The default `<ItemMedia />` only centers its content, so an Avatar or AvatarGroup drops straight in.

### People

A grouped list of people. Separators start where the text starts, whatever sits in the media slot, so they line up under the names.

### Actions

`<ItemActions />` holds buttons at the end of the row. Keep the item itself static when it holds buttons, so there's never a button inside a link.

### Header and footer

`<ItemHeader />` and `<ItemFooter />` take a full row above and below the content.

### Separator

In a default group, place an `<ItemSeparator />` between items yourself.

### Long content

Titles clamp to one line and descriptions to two. Unbroken strings wrap instead of widening the row.

### Right to left

Padding, separator insets and the chevron follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves to the next interactive item, in source order like any link or button. |
| `Enter` | Follows a link item or presses a button item. |
| `Space` | Presses a button item or toggles a label item. |

## Accessibility

- A group is a list when its items are plain rows. Items rendered as links or buttons keep their own role, and the group drops the list role so the markup stays valid. Render the group as `<ul>` and items as `<li>` wrapping links if you want both.
- `<ItemMedia variant="icon" />` and the chevron are hidden from screen readers. Give images real alt text when they carry meaning.
- The highlight is decoration. Keyboard focus shows the focus ring, and the highlight never moves focus or changes the tab order.

## API reference

Every part renders a `<div>` by default and accepts `render` and its element's attributes.

### Item

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline" \| "muted"` | `"default"` |  |
| `size` | `"default" \| "sm" \| "xs"` | `"default"` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="item"` | Target items in CSS. |
| `data-variant` | The current variant. |
| `data-size` | The current size. |
| `data-interactive` | Present when the item renders as a link, button or label. |
| `data-highlighted` | Present while the group highlight is on it. |
| `--item-radius` | Corner radius. Media corners derive from it. Set by size. |
| `--item-px / --item-py / --item-gap` | Padding and gap. Set by size. |
| `--item-media-size` | Size of icon and image media. Set by size. |
| `--item-inset` | Where a grouped separator starts. Measured to line up with ItemContent, whatever the media is. |

### ItemGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "grouped"` | `"default"` | grouped puts items on one surface with automatic separators. |
| `highlight` | `boolean` | `true` | Show one highlight that glides between interactive items on hover. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="item-group"` | Target groups in CSS. |
| `data-variant` | The current variant. |
| `data-highlight` | Present when the hover highlight is on. |
| `--item-group-radius` | Corner radius of a grouped surface. The first and last items follow it. |
| `data-slot="item-highlight"` | The highlight element, with data-visible and data-pressed. |

### ItemMedia

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "icon" \| "image"` | `"default"` | icon puts the icon on a tile and hides it from screen readers. image crops to a square. Both have corners concentric with the item. |
| `tone` | `"gray" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "sky" \| "blue" \| "indigo" \| "purple" \| "pink"` | – | With the icon variant, fills the tile with a solid color and turns the icon white, like iOS Settings. Leave it unset for a neutral tile. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="item-media"` | Target media in CSS. |
| `data-variant` | The current variant. |
| `data-tone` | The tile color, when tone is set on an icon. |
| `--item-media-tone` | The tile color. Set it to any color for a custom tone. |

### ItemContent

| Attribute | Description |
| --- | --- |
| `data-slot="item-content"` | Grows to fill the row. A second content block hugs its text. |

### ItemTitle

| Attribute | Description |
| --- | --- |
| `data-slot="item-title"` | Clamped to one line. |

### ItemDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="item-description"` | Clamped to two lines. |

### ItemActions

| Attribute | Description |
| --- | --- |
| `data-slot="item-actions"` | Target the actions in CSS. |

### ItemHeader and ItemFooter

| Attribute | Description |
| --- | --- |
| `data-slot="item-header"` | A full-width row above the content. |
| `data-slot="item-footer"` | A full-width row below the content. |

### ItemChevron

A trailing chevron that nudges toward the reading direction when its item is hovered. Accepts every Tabler icon prop.

| Attribute | Description |
| --- | --- |
| `data-slot="item-chevron"` | Target the chevron in CSS. |

### ItemSeparator

| Attribute | Description |
| --- | --- |
| `data-slot="item-separator"` | A hairline with role="separator". |

---

# Kbd

> Key caps for shortcuts that show the right symbols on every platform, read them out properly and press down with the real keys.

Docs: https://hextaui.com/docs/kbd
Markdown: https://hextaui.com/docs/kbd.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/kbd.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/kbd.tsx`, `lib/hotkey.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd"
```

```tsx
<KbdGroup keys="mod+k" />
<Kbd keys="escape" />
<Kbd>K</Kbd>
```

Write shortcuts once with `keys` and they show as ⌘K on a Mac and Ctrl K on Windows and Linux. Or pass any content as children for full control.

## Composition

```text
Kbd

KbdGroup
└── Kbd
```

## Examples

### Variants

`keycap` has a hairline edge and a 1px lip so it reads as a physical key. `flat` is a quiet fill for dense places like menus.

### Sizes

`sm` sits in small text, `default` next to body text and `lg` in headings or on its own.

### Shortcuts

`<KbdGroup />` splits a combo into one cap per key. A space starts a sequence, joined by `separator`. `<Kbd />` with `keys` keeps the whole combo in one cap.

### Live keys

With `listen`, a cap presses down while its real key is held. It only watches, so it never blocks, delays or changes what you type. Letters match by physical key, so Option and Shift don't confuse them.

### In a button

Inside a button, the cap takes its colors from the button's text, so it fits every variant.

### Icons and actions

Put icons in a cap for actions without a key name, and give them a visually hidden label.

### Right to left

Shortcuts stay in left-to-right order inside right-to-left text, the way they're printed on the keyboard.

## Accessibility

- Symbols like ⌘ and ⇧ are hidden from screen readers and replaced with their names, so `keys="mod+shift+p"` is read as "Command Shift P".
- Caps render as `<kbd>`, and a group nests them in another `<kbd>`, which is how HTML marks a key combination.
- Showing a shortcut doesn't bind it. Register the key handler yourself.
- The press effect is decoration, with a color change in place of movement when reduced motion is on. Before hydration, every platform sees the Apple symbols.

## API reference

Both parts render a `<kbd>` and accept `render` and its attributes.

### Kbd

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` | `string` | – | Keys joined with +, like "mod+shift+p". mod is ⌘ on Apple devices and Ctrl elsewhere. Names such as alt, enter, escape, up and space become symbols or short words, and get a spoken name for screen readers. |
| `variant` | `"keycap" \| "flat"` | `"keycap"` | Inherited from KbdGroup when unset. |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` | Inherited from KbdGroup when unset. |
| `listen` | `boolean` | `false` | Press the cap while its real key is held. Works with keys or a plain key name as children. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<kbd>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="kbd"` | Target caps in CSS. |
| `data-variant` | The current variant. |
| `data-size` | The current size. |
| `data-pressed` | Present while the real key is held. |

### KbdGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keys` | `string` | – | Keys joined with +, like "mod+shift+p". mod is ⌘ on Apple devices and Ctrl elsewhere. Names such as alt, enter, escape, up and space become symbols or short words, and get a spoken name for screen readers. Spaces separate the steps of a sequence. |
| `separator` | `ReactNode` | `"then"` | Shown between the steps of a sequence. |
| `variant` | `"keycap" \| "flat"` | – | Passed to every cap inside. |
| `size` | `"sm" \| "default" \| "lg"` | – | Passed to every cap inside. |
| `listen` | `boolean` | – | Passed to every cap inside. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<kbd>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="kbd-group"` | Target groups in CSS. |
| `data-slot="kbd-separator"` | The text between sequence steps. |

---

# Label

> A label that follows its control, dimming when it's disabled and marking it required or optional on its own.

Docs: https://hextaui.com/docs/label
Markdown: https://hextaui.com/docs/label.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/label.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react cn
```

Copy `components/ui/label.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Label } from "@/components/ui/label"
```

```tsx
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" />
```

Point `htmlFor` at a control's `id`, or wrap the control. Either way the label finds it and follows its state. Inside a `<Field />`, use `<FieldLabel />`, which wires up the id for you.

## Examples

### Follows its control

The label dims and shows a not-allowed cursor while its control is disabled, and exposes `data-required`, `data-invalid` and `data-readonly` for your own styles. It keeps up when the control changes.

### Required and optional

`indicator="optional"` tags controls without `required`, and `indicator="required"` adds an asterisk to controls with it. The mark is hidden from screen readers, which already announce required fields.

### Checkbox

Wrap a checkbox so the whole label toggles it, or place the label beside it with htmlFor. A disabled checkbox dims its label either way.

### Icon

Icons inside a label are sized and muted to sit next to the text.

### Long content

Long labels wrap, and unbroken strings break instead of widening the layout.

### Right to left

Gaps and the indicator follow the reading direction.

## Accessibility

- Clicking the label focuses or toggles its control, so it's a bigger target than the control alone.
- Double-clicking the label text doesn't select it. Double-clicks on a control inside the label work as usual.
- Every control needs a name. When there's no visible label, use `aria-label` on the control instead.

## API reference

Renders a `<label>` and accepts its attributes.

### Label

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `htmlFor` | `string` | – | The id of the control. Leave it out when the label wraps the control. |
| `indicator` | `"required" \| "optional"` | – | Mark the label from the control's required state. Off by default. |
| `optionalText` | `ReactNode` | `"Optional"` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<label>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="label"` | Target labels in CSS. |
| `data-disabled` | Present while the control is disabled. |
| `data-required` | Present while the control is required. |
| `data-invalid` | Present while the control is invalid, after the user has interacted or when aria-invalid is set. |
| `data-readonly` | Present while the control is read-only. |
| `data-slot="label-indicator"` | The required or optional mark. |

---

# Marker

> Quiet notes between content, like date dividers and system events, with sticky dates and times that read as Today or Yesterday.

Docs: https://hextaui.com/docs/marker
Markdown: https://hextaui.com/docs/marker.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/marker.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/marker.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Marker,
  MarkerContent,
  MarkerIcon,
  MarkerTime,
} from "@/components/ui/marker"
```

```tsx
<Marker variant="separator" sticky>
  <MarkerContent>
    <MarkerTime date={message.sentAt} />
  </MarkerContent>
</Marker>
```

## Composition

```text
Marker
├── MarkerIcon
└── MarkerContent
    └── MarkerTime
```

## Examples

### Variants

`default` is a quiet note, `separator` centers it between two hairlines, and `border` underlines it like a section heading.

### Sticky dates

With `sticky`, a marker stays at the top of its scroll area. Once it sticks, its lines fade and the label turns into a floating pill so it stays readable over messages. Put each day in its own section so the next date pushes the previous one away.

### Relative dates

`<MarkerTime />` renders a `<time>` that reads Today, Yesterday, a weekday within the last week, then a short date. It updates itself at midnight. Pass `format` for your own wording.

### Activity

Render markers as list items for an activity log. Links inside are underlined until hovered.

### Long content

Notes wrap and unbroken strings break instead of widening the layout. Separator lines keep a minimum length on both sides.

### Right to left

Icons and text follow the reading direction.

## Accessibility

- Markers are plain text, so screen readers read them in place. Icons are hidden from them.
- `<MarkerTime />` keeps the exact moment in `dateTime` while showing a friendly label.
- The sticky pill appears without motion when reduced motion is on.

## API reference

### Marker

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "separator" \| "border"` | `"default"` |  |
| `sticky` | `boolean` | `false` | Stick to the top of the scroll area and become a pill while stuck. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="marker"` | Target markers in CSS. |
| `data-variant` | The current variant. |
| `data-sticky` | Present when sticky is on. |
| `data-stuck` | Present while the marker is stuck to the top. |
| `--marker-sticky-top` | Distance from the top while stuck. Defaults to 0.5rem. |

### MarkerContent

| Attribute | Description |
| --- | --- |
| `data-slot="marker-content"` | The text. Becomes the pill while stuck. |

### MarkerIcon

| Attribute | Description |
| --- | --- |
| `data-slot="marker-icon"` | A 16px icon box, hidden from screen readers. |

### MarkerTime

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `date` | `Date \| string \| number` | – | Required. Anything new Date() accepts. |
| `locale` | `Intl.LocalesArgument` | `"en-US"` | Fixed by default so the server and browser agree. |
| `format` | `(date: Date) => ReactNode` | – | Replace the relative label with your own. |

| Attribute | Description |
| --- | --- |
| `data-slot="marker-time"` | The time element, with an ISO dateTime. |

---

# Menubar

> A desktop-style bar of menus with one highlight that slides between open menus and instant switching as you sweep across.

Docs: https://hextaui.com/docs/menubar
Markdown: https://hextaui.com/docs/menubar.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/menubar.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/menubar.tsx`, `components/ui/dropdown-menu.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarShortcut,
  MenubarTrigger,
} from "@/components/ui/menubar"
```

```tsx
<Menubar aria-label="Editor">
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent>
      <MenubarItem>
        New tab <MenubarShortcut>⌘T</MenubarShortcut>
      </MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

Each `<MenubarMenu />` is a Dropdown menu, so items, checkbox and radio items, submenus, labels and shortcuts work and look exactly the same. Open a menu, then move the pointer or press the arrow keys to sweep across the bar.

## Composition

```text
Menubar
└── MenubarMenu
    ├── MenubarTrigger
    └── MenubarContent
        ├── MenubarGroup
        │   ├── MenubarLabel
        │   └── MenubarItem
        │       └── MenubarShortcut
        ├── MenubarCheckboxItem
        ├── MenubarRadioGroup
        │   └── MenubarRadioItem
        ├── MenubarSeparator
        └── MenubarSub
            ├── MenubarSubTrigger
            └── MenubarSubContent
```

## Examples

### Trigger icons

Put an icon before a trigger's label, or use an icon on its own with an `aria-label`. Icon-only triggers get a square shape.

### Icons

Put an icon before the label. Use `variant="destructive"` on items that delete or can't be undone.

### Disabled

Disable a single menu with `disabled` on `<MenubarMenu />`, or the whole bar on `<Menubar />`. Arrow keys skip disabled menus.

### Vertical

`orientation="vertical"` stacks the menus and switches navigation to the up and down arrows. Open the menus to the side with `side="inline-end"`.

### Right to left

Menus, submenus and arrow keys follow the reading direction. Shortcuts stay in keyboard order.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus into the menubar, then out of it. |
| `←` `→` | Moves between menus. With a menu open, opens the next one instead. |
| `Enter` `Space` `↓` | Opens the focused menu. |
| `↑` `↓` | Moves between items in an open menu. |
| `→` | Opens a submenu from its trigger. |
| `Esc` | Closes the open menu and returns focus to its trigger. |

## Accessibility

- Give the menubar a name with `aria-label`. It renders `role="menubar"` and each trigger is a menu item, so screen readers announce it as an application menu.
- The bar is a single tab stop. Arrow keys move between menus, so the page's tab order stays short.
- The sliding highlight is decoration. With reduced motion it just appears on the open menu.

## API reference

Menu parts accept the same props as their Dropdown menu counterparts.

### Menubar

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `loopFocus` | `boolean` | `true` | Wrap from the last menu back to the first. |
| `modal` | `boolean` | `true` | Block page scrolling and outside clicks while a menu is open. |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="menubar"` | Target the bar in CSS. |
| `data-orientation` | The orientation. |
| `data-has-submenu-open` | Present while any menu in the bar is open. |
| `data-slot="menubar-highlight"` | The sliding background behind the open trigger, with data-visible. |
| `--menubar-radius` | Corner radius of the bar. Triggers and the highlight derive theirs from it. |

### MenubarMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |

### MenubarTrigger

| Attribute | Description |
| --- | --- |
| `data-slot="menubar-trigger"` | Target triggers in CSS. |
| `data-popup-open` | Present while its menu is open. |
| `data-disabled` | Present when disabled. |

### MenubarContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"bottom"` |  |
| `align` | `"start" \| "center" \| "end"` | `"start"` |  |
| `sideOffset` | `number` | `8` |  |
| `alignOffset` | `number` | `-4` | Lines the menu's items up with the trigger's label. |

| Attribute | Description |
| --- | --- |
| `data-slot="menubar-content"` | Target menus in CSS. |
| `data-instant="group"` | Present when the menu opened by sweeping from another one. It switches without animating. |

### Items

`MenubarItem`, `MenubarCheckboxItem`, `MenubarRadioGroup`, `MenubarRadioItem`, `MenubarGroup`, `MenubarLabel`, `MenubarSeparator`, `MenubarShortcut`, `MenubarSub`, `MenubarSubTrigger` and `MenubarSubContent` are the Dropdown menu parts with `menubar-*` slots. See the Dropdown menu API for their props.

---

# Message

> A chat message row with an avatar, name, bubbles and status, where new messages rise in from the sender's side.

Docs: https://hextaui.com/docs/message
Markdown: https://hextaui.com/docs/message.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/message.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/message.tsx`, `components/ui/bubble.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Message,
  MessageAvatar,
  MessageContent,
  MessageFooter,
  MessageGroup,
  MessageHeader,
} from "@/components/ui/message"
```

```tsx
<MessageGroup>
  <Message align="end">
    <MessageContent>
      <Bubble>
        <BubbleContent>On my way.</BubbleContent>
      </Bubble>
      <MessageFooter>Read</MessageFooter>
    </MessageContent>
  </Message>
</MessageGroup>
```

A message lays out an avatar, a name, one or more `<Bubble />`s and a status line. Bubbles inherit the message's `align`, so you set it once.

## Composition

```text
MessageGroup
└── Message
    ├── MessageAvatar
    └── MessageContent
        ├── MessageHeader
        ├── Bubble
        └── MessageFooter
```

## Examples

### Alignment

`align="end"` puts the avatar and bubbles on the other side for your own messages.

### Header and footer

`<MessageHeader />` holds the name and time, and `<MessageFooter />` a single line of status. The avatar always lines up with the last bubble, with or without a footer.

### Assistant

A `ghost` bubble spans the full width for long answers, and an icon in `<MessageAvatar />` becomes a round tile.

### Long content

Bubbles wrap long links, and header and footer text can truncate without pushing the avatar.

### Right to left

Start and end swap sides, and new messages grow from the matching corner.

## Accessibility

- Messages are plain content. For a live chat, wrap the list in a `role="log"` element so screen readers read new messages as they arrive.
- Put the sender's name in a header or in visually hidden text, since alignment alone doesn't say who wrote a message.
- The entrance only plays for messages added after the list first renders. With reduced motion they fade in.

## API reference

Every part renders a `<div>` and accepts `render`.

### MessageGroup

The thread. Messages added after its first render animate in.

| Attribute | Description |
| --- | --- |
| `data-slot="message-group"` | Target the thread in CSS. |

### Message

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "end"` | `"start"` | Side of the conversation. Bubbles inherit it. |
| `animated` | `boolean` | `true` | Rise in when added to a MessageGroup after its first render. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="message"` | Target messages in CSS. |
| `data-align` | The side. |
| `data-entering` | Present on messages that animate in. |

### MessageAvatar

| Attribute | Description |
| --- | --- |
| `data-slot="message-avatar"` | Lines up with the last bubble. A bare icon or image is sized to 32px. |

### MessageContent

| Attribute | Description |
| --- | --- |
| `data-slot="message-content"` | Stacks the header, bubbles and footer. |

### MessageHeader and MessageFooter

| Attribute | Description |
| --- | --- |
| `data-slot="message-header"` | Name and time above the bubbles. |
| `data-slot="message-footer"` | One line of status below. Keep it to a single line so the avatar stays aligned. |

---

# Message scroller

> A chat scroll area that follows new messages, keeps your place while you read back, and counts what you missed on the jump button.

Docs: https://hextaui.com/docs/message-scroller
Markdown: https://hextaui.com/docs/message-scroller.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/message-scroller.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @shadcn/react @tabler/icons-react cn
```

Copy `components/ui/message-scroller.tsx`, `components/ui/button.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@/components/ui/message-scroller"
```

```tsx
<MessageScrollerProvider>
  <MessageScroller>
    <MessageScrollerViewport aria-label="Conversation">
      <MessageScrollerContent>
        {messages.map((message) => (
          <MessageScrollerItem key={message.id} messageId={message.id}>
            <Message>…</Message>
          </MessageScrollerItem>
        ))}
      </MessageScrollerContent>
    </MessageScrollerViewport>
    <MessageScrollerButton />
  </MessageScroller>
</MessageScrollerProvider>
```

Give every item a stable `messageId`. The scroller uses it to follow new messages, keep your place and count what you haven't seen. Pair it with `<Message />` and `<Bubble />` for the rows.

## Composition

```text
MessageScrollerProvider
└── MessageScroller
    ├── MessageScrollerViewport
    │   └── MessageScrollerContent
    │       └── MessageScrollerItem
    └── MessageScrollerButton
```

## Examples

### Group chat

Anchors don't have to be messages. Here a `<Marker />` for someone joining starts the turn. Scroll up, receive messages, and the jump button counts what arrived while you were away.

### Keeping context

`scrollPreviousItemPeek` keeps a slice of the previous turn above a newly anchored one, so the thread still feels continuous. Try each amount, then ask the next question.

### Opening saved threads

`defaultScrollPosition="last-anchor"` reopens a conversation at its last question, with the answer below, instead of dropping the reader mid-answer at the bottom.

### Loading earlier messages

Older messages added above keep what you're reading in place (`preserveScrollOnPrepend`, on by default).

### Jumping to messages

`useMessageScroller` drives the thread from outside it, and `useMessageScrollerVisibility` reports the current turn, so the outline highlights where you are.

## Hooks

Inside the provider, these hooks let your own controls scroll the thread and react to what's on screen.

```tsx
const { scrollToEnd, scrollToMessage, scrollToStart } = useMessageScroller()
const { start, end } = useMessageScrollerScrollable()
const { visibleMessageIds, currentAnchorId } = useMessageScrollerVisibility()
```

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Focuses the conversation. The jump button joins the tab order only while it's showing. |
| `↑` `↓` | Scrolls the conversation. |
| `Page Up` `Page Down` | Scrolls by a screen. |
| `Home` `End` | Jumps to the first or latest message. |

## Accessibility

- The viewport is a labelled, focusable region and the content is a `role="log"`, so screen readers announce new messages as they arrive. Give the viewport an `aria-label`.
- The jump button's label says how many messages are new, so "3 new messages" is read out, not just an arrow.
- Following new messages never moves you while you're reading back. It only resumes once you're at the bottom again.

## API reference

### MessageScrollerProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoScroll` | `boolean` | `false` | Follow new messages while the reader is at the bottom. |
| `defaultScrollPosition` | `"start" \| "end" \| "last-anchor"` | `"end"` | Where the thread opens. |
| `scrollPreviousItemPeek` | `number` | `64` | How much of the previous item stays visible above a new anchor. |
| `scrollEdgeThreshold` | `number` | – | Pixels from an edge that still count as at it. |
| `scrollMargin` | `number` | – | Space kept above messages scrolled into view. |

### MessageScrollerViewport

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preserveScrollOnPrepend` | `boolean` | `false` | Keep the reading position when messages are added above. |
| `aria-label` | `string` | – | Names the conversation region. |

| Attribute | Description |
| --- | --- |
| `data-scrollable="start end"` | Which edges have more to scroll. Drives the edge fades. |
| `data-autoscrolling` | Present while following new messages. The scrollbar hides. |
| `--scroller-fade-start / --scroller-fade-end` | Size of the edge fades. They animate in and out. |

### MessageScrollerItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `messageId` | `string` | – | Stable id for following, anchors and counts. |
| `scrollAnchor` | `boolean` | `false` | Scroll this item to the top when it arrives, with defaultScrollPosition="last-anchor". |

### MessageScrollerButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `"start" \| "end"` | `"end"` |  |
| `showUnseen` | `boolean` | `true` | Grow into a pill that counts messages that arrived while you were scrolled up. |
| `unseenLabel` | `(count: number) => ReactNode` | `"3 new messages"` |  |
| `variant` | `Button variant` | `"outline"` |  |
| `behavior` | `ScrollBehavior` | `"smooth"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="message-scroller-button"` | Target the button in CSS. |
| `data-active` | "true" while there's somewhere to jump to. |
| `data-unseen` | The unseen count, while it's above zero. |

---

# Native select

> The browser's own select, styled to match Input, with a quiet placeholder, Field support and the OS picker on every device.

Docs: https://hextaui.com/docs/native-select
Markdown: https://hextaui.com/docs/native-select.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/native-select.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/native-select.tsx`, `components/ui/input.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  NativeSelect,
  NativeSelectOptGroup,
  NativeSelectOption,
} from "@/components/ui/native-select"
```

```tsx
<NativeSelect>
  <NativeSelectOption value="">Select a fruit</NativeSelectOption>
  <NativeSelectOption value="apple">Apple</NativeSelectOption>
  <NativeSelectOption value="banana">Banana</NativeSelectOption>
</NativeSelect>
```

An option with an empty `value` acts as the placeholder: it shows in muted text until something is chosen. Put `className` on the select to size its wrapper, for example `w-full`.

## Composition

```text
NativeSelect
├── NativeSelectOption
└── NativeSelectOptGroup
    └── NativeSelectOption
```

## Examples

### Groups

`<NativeSelectOptGroup />` organizes options under headings in the OS picker.

### Sizes

Sizes, borders, focus rings and invalid styles match Input exactly, so the two line up in a row.

### Field

Inside a `<Field />`, the label and description connect on their own and errors show as the value changes. Submit without a plan and the select turns red, shakes once, and the browser points to it.

### Invalid

Set `aria-invalid` and link the message with `aria-describedby`.

### Disabled

Disable the whole select, or single options that aren't available.

### Controlled

Pass `value` and `onChange` like a regular select.

### Long content

Long selected labels end with an ellipsis instead of running under the chevron.

### Right to left

The chevron and padding move to the other side.

## Native select or Select?

- Use Native select for simple lists, especially on phones, where the OS picker is the fastest and most familiar way to choose.
- Use Combobox when people need to search, or when options need icons, descriptions or custom layouts.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Focuses the select. |
| `Space` `Enter` | Opens the OS picker. |
| `↑` `↓` | Changes the selection, or moves in the open picker. |
| `A–Z` | Jumps to the option that starts with the typed text. |

## API reference

`<NativeSelect />` accepts every select attribute. The option parts accept their element's attributes.

### NativeSelect

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `htmlSize` | `number` | – | The native size attribute, renamed because size is the variant. |
| `shake` | `boolean` | `true` | Shake once when a form submit finds it invalid. |
| `className` | `string` | – | Applied to the wrapper, so it sizes the whole control. |
| `value` | `string` | – |  |
| `defaultValue` | `string` | – |  |
| `disabled` | `boolean` | `false` |  |
| `required` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="native-select-wrapper"` | The wrapper, with data-size. |
| `data-slot="native-select"` | The select element. |
| `data-slot="native-select-icon"` | The chevron. Darkens on hover and focus. |
| `data-invalid` | Present when a surrounding Field is invalid. |

### NativeSelectOption and NativeSelectOptGroup

| Attribute | Description |
| --- | --- |
| `data-slot="native-select-option"` | An option. |
| `data-slot="native-select-optgroup"` | A labelled group of options. |

---

# Navigation menu

> Site navigation with dropdowns, or one full-width panel that stays open while its content slides between menus.

Docs: https://hextaui.com/docs/navigation-menu
Markdown: https://hextaui.com/docs/navigation-menu.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/navigation-menu.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/navigation-menu.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@/components/ui/navigation-menu"
```

```tsx
<NavigationMenu variant="panel" aria-label="Main">
  <NavigationMenuList>
    <NavigationMenuItem>
      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink href="/components">Components</NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
    <NavigationMenuItem>
      <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>
```

With `variant="panel"`, one card spans the whole bar. Moving between triggers keeps it open and in place: only the content slides toward the direction you moved, and the height eases to fit. Nothing closes, reopens or jumps.

## Composition

```text
NavigationMenu
└── NavigationMenuList
    ├── NavigationMenuItem
    │   ├── NavigationMenuTrigger
    │   └── NavigationMenuContent
    │       └── NavigationMenuLink
    └── NavigationMenuItem
        └── NavigationMenuLink
```

## Examples

### Dropdown

The default `dropdown` variant opens a card under each trigger. Moving to the next trigger glides the same card over and resizes it to the new content.

### Current page

Links in the bar look like triggers. Mark the current page with `active`, which also sets `aria-current="page"`.

### Right to left

Content slides follow the direction you move, which flips in right-to-left layouts.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves through the bar, and from an open trigger into its content. |
| `Enter` `Space` | Opens or closes the focused trigger's menu. |
| `↑` `↓` | Moves between links in the open content. |
| `←` `→` | Moves between triggers in the bar. |
| `Esc` | Closes the menu and returns focus to its trigger. |

## Accessibility

- The root renders a `<nav>`. Give it an `aria-label` when the page has more than one.
- Triggers are buttons that report whether their menu is open, and focus returns to them when the menu closes.
- The content slide and the sliding highlight turn into fades when reduced motion is on.

## API reference

### NavigationMenu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"dropdown" \| "panel"` | `"dropdown"` | dropdown opens under each trigger. panel opens one full-width card under the bar that stays put while content slides. |
| `showSafeArea` | `boolean` | `false` | Draws the safe area that keeps a menu open while the pointer heads into it. For debugging and demos. |
| `align` | `"start" \| "center" \| "end"` | `"start", or "center" for panel` |  |
| `sideOffset` | `number` | `8` |  |
| `value` | `any` | – |  |
| `defaultValue` | `any` | – |  |
| `onValueChange` | `(value, details) => void` | – |  |
| `delay` | `number` | `50` | Wait before opening on hover, in ms. |
| `closeDelay` | `number` | `50` | Wait before closing after the pointer leaves, in ms. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="navigation-menu"` | The nav, with data-variant. |
| `data-slot="navigation-menu-highlight"` | The background that slides between open triggers. |
| `data-slot="navigation-menu-popup"` | The card. Its height eases through --popup-height. |

### NavigationMenuTrigger

| Attribute | Description |
| --- | --- |
| `data-slot="navigation-menu-trigger"` | Target triggers in CSS. |
| `data-popup-open` | Present while its menu is open. The chevron flips. |

### NavigationMenuContent

| Attribute | Description |
| --- | --- |
| `data-slot="navigation-menu-content"` | A menu's content, with data-variant. |
| `data-activation-direction` | "left", "right", "up" or "down": where the previous trigger was. Drives the slide. |
| `--navigation-menu-link-radius` | Link corner radius, concentric with the card. |

### NavigationMenuLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Marks the current page. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<a>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="navigation-menu-link"` | Target links in CSS. In the bar they size themselves like triggers. |
| `data-active` | Present on the current page. |

---

# Number flow

> Animated numbers where only the changed digits spin, with any Intl format and locale.

Docs: https://hextaui.com/docs/number-flow
Markdown: https://hextaui.com/docs/number-flow.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/number-flow.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add cn
```

Copy `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { NumberFlow } from "@/components/ui/number-flow"
```

```tsx
<NumberFlow
  value={1234.5}
  format={{ style: "currency", currency: "USD" }}
/>
```

## Examples

### Only changed digits move

Each digit is its own column. Going from 22 to 23 spins only the ones digit; the tens digit stays still. Digits that appear or disappear, like the third digit in 99 → 100, slide their width in or out.

### Trend

`trend` sets which way digits spin. `auto` spins up when the value grows and down when it shrinks, `up` and `down` force a direction, and `shortest` takes the nearest way round the wheel.

### Formats

`format` and `locales` take any `Intl.NumberFormat` options. Currency symbols, separators and signs stay still while the digits move, and non-Latin numerals spin in their own script.

### Timing

Tune the motion with `duration` and `easing`, or turn it off with `animated={false}`. Reduced motion settings turn it off automatically.

### Interruptions and events

A new value mid-spin continues from where each digit is, so rapid updates never jump. `onAnimationsStart` and `onAnimationsFinish` fire once per batch of digits.

### Inline and in badges

It renders an inline `<span>` that sits on the text baseline, and tabular digits keep its width steady while digits spin. `BadgeCount` uses it for counts that cap at a maximum.

### Right to left

Numbers always read left to right, even inside a right-to-left layout, matching how browsers render them.

## Accessibility

- Screen readers read the real formatted number. The spinning columns are hidden from assistive tech, and characters that are leaving are hidden while they animate out.
- It is not a live region. Wrap it in an element with `aria-live="polite"` when changes should be announced.
- With reduced motion enabled, values update instantly with no spin.

## API reference

Accepts every `<span>` attribute except `children` and `prefix`.

### NumberFlow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | – | Required. |
| `locales` | `Intl.LocalesArgument` | `"en-US"` |  |
| `format` | `Intl.NumberFormatOptions` | – | Passed to Intl.NumberFormat. |
| `prefix` | `string` | – | Static text before the number. |
| `suffix` | `string` | – | Static text after the number. |
| `trend` | `"auto" \| "up" \| "down" \| "shortest"` | `"auto"` |  |
| `duration` | `number` | `600` | Spin duration in milliseconds. |
| `easing` | `string` | `easeSpring` | Any CSS easing value. |
| `animated` | `boolean` | `true` |  |
| `onAnimationsStart` | `() => void` | – | Called when a batch of digits starts moving. |
| `onAnimationsFinish` | `() => void` | – | Called when the latest batch settles. Skipped if a newer value interrupts it. |

| Attribute | Description |
| --- | --- |
| `data-slot="number-flow"` | The root span. |
| `data-slot="number-flow-digit"` | Each digit cell. |
| `data-slot="number-flow-symbol"` | Separators, signs, symbols, prefix and suffix. |
| `data-slot="number-flow-column"` | The spinning column inside a digit cell. |
| `data-digit` | The digit a column is resting on, 0–9. |

---

# Pagination

> Page navigation that keeps every button in place, glides to the current page and jumps to any page from the ellipsis.

Docs: https://hextaui.com/docs/pagination
Markdown: https://hextaui.com/docs/pagination.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/pagination.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/pagination.tsx`, `components/ui/button.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Pagination } from "@/components/ui/pagination"
```

```tsx
const [page, setPage] = React.useState(1)

<Pagination page={page} count={25} onPageChange={setPage} />
```

Give `Pagination` a `count` and it builds the whole bar. It always shows the same number of slots, so Previous, Next and the numbers never shift under your cursor while you click through pages. Leave `count` out to compose the parts yourself.

## Composition

```text
Pagination
└── PaginationContent
    ├── PaginationItem
    │   └── PaginationPrevious
    ├── PaginationItem
    │   └── PaginationLink
    ├── PaginationItem
    │   └── PaginationEllipsis
    └── PaginationItem
        └── PaginationNext
```

## Examples

### Jump to a page

Click an ellipsis to type a page number. Enter jumps, an out-of-range number shakes the field, and Esc puts the ellipsis back. Turn it off with `jump={false}`.

### Compact

When the bar doesn't fit its container, it switches to Previous, “Page 4 of 24” and Next, and switches back when there's room. The label is a jump field too. Force either layout with `compact`.

### Links

With `getPageHref`, every page is a real link, so it can be opened in a new tab. Plain clicks still call `onPageChange`.

### Composable

Without `count`, build the bar from the parts, as in shadcn/ui. Pass `render` to use your router's link.

### Right to left

`usePagination` returns the page and ellipsis items for custom layouts. Chevrons flip in right-to-left text.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves into and out of the bar. Previous and Next stay focusable at the ends. |
| `←` `→` | Moves between Previous, the pages and Next. Flips in right-to-left layouts. |
| `Home` `End` | Moves to the first or last item. |
| `Enter` | Opens the focused page or the page field. In the field, jumps to that page and focuses it. |
| `Esc` | Closes the page field and returns focus to the ellipsis. |

## Accessibility

- The root is a `<nav>` labelled “Pagination”, and the current page has `aria-current="page"`.
- At the first and last page, Previous and Next use `aria-disabled` instead of `disabled`, so focus isn't lost when you reach the end.
- The sliding indicator becomes a fade when reduced motion is on.

## API reference

### Pagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | – | Total pages. When set, the bar is built for you; leave it out to compose the parts. |
| `page` | `number` | – |  |
| `defaultPage` | `number` | `1` |  |
| `onPageChange` | `(page: number) => void` | – |  |
| `getPageHref` | `(page: number) => string` | – | Renders pages as links instead of buttons. |
| `siblings` | `number` | `1` | Pages shown on each side of the current one. |
| `boundaries` | `number` | `1` | Pages always shown at the start and end. |
| `compact` | `boolean \| "auto"` | `"auto"` | auto switches to Previous, “Page x of y” and Next when the bar doesn't fit. |
| `jump` | `boolean` | `true` | Lets the ellipsis open a page field. |

| Attribute | Description |
| --- | --- |
| `data-slot="pagination"` | The nav. |
| `data-slot="pagination-indicator"` | The background that glides to the current page. |

### PaginationLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | Marks the current page with aria-current="page". |
| `disabled` | `boolean` | `false` | Sets aria-disabled and ignores clicks. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<a>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="pagination-link"` | Target page links in CSS. |
| `data-active` | Present on the current page. |

### PaginationPrevious / PaginationNext

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `ReactNode` | `"Previous" / "Next"` | Pass null for an icon-only button. |
| `disabled` | `boolean` | `false` |  |

### PaginationEllipsis

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onJump` | `(page: number) => void` | – | Makes the ellipsis a page field. Without it, the ellipsis is decorative. |
| `count` | `number` | – | The highest page the field accepts. |

### usePagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | `number` | – |  |
| `count` | `number` | – |  |
| `siblings` | `number` | `1` |  |
| `boundaries` | `number` | `1` |  |

Returns `items`, the clamped `page` and `count`, and `hasPrevious` and `hasNext`. See the [usePagination guide](https://hextaui.com/docs/use-pagination) for building your own pager.

---

# Popover

> A floating panel anchored to a trigger that resizes smoothly with its content and follows the trigger’s direction.

Docs: https://hextaui.com/docs/popover
Markdown: https://hextaui.com/docs/popover.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/popover.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react cn
```

Copy `components/ui/popover.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover"
```

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    Open
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Dimensions</PopoverTitle>
      <PopoverDescription>Set the dimensions for the layer.</PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>
```

## Composition

```text
Popover
├── PopoverTrigger
└── PopoverContent
    ├── PopoverHeader
    │   ├── PopoverTitle
    │   └── PopoverDescription
    └── PopoverClose
```

## Examples

### Content that changes size

When the content grows or shrinks, the popup animates its height instead of jumping. Continuous changes, like typing, follow the content directly so nothing lags behind.

### Controlled

Pass `open` and `onOpenChange` to drive it from your own state. The second argument tells you why it changed, such as `trigger-press`, `outside-press` or `escape-key`.

### Placement

`side` and `align` set the preferred position. When there is no room, the popup flips to the other side and shifts to stay on screen, keeping 8px from the edges.

### Open on hover

Set `openOnHover` on the trigger for preview cards. `delay` and `closeDelay` keep it from flickering as the pointer passes over.

### Detached triggers

Create a handle with `createPopoverHandle` to share one popover between several triggers anywhere in the tree. Each trigger passes a `payload`, and the popup renders it through a function child.

### With a calendar

Use `className="w-auto p-0"` to fit content that brings its own padding. The popup follows the calendar as it changes months.

### Nested

A popover inside another popover or a sheet layers above its parent. Clicks inside the child keep the parent open, and Escape closes only the topmost layer.

### Long content

Unbroken text wraps inside the popup. When the content is taller than the space available, the popup scrolls inside instead of running off screen.

### Modal

With `modal`, page scroll is locked and outside clicks only dismiss the popover. Render a `<PopoverClose />` inside so focus can be trapped and touch screen readers have a way out.

### Disabled

A `disabled` trigger never opens its popover.

### Right to left

The popup picks up the direction of the trigger that opened it, even though it renders in a portal. Logical sides like `inline-end` flip with it.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | On the trigger, opens or closes the popover. Focus moves into the popup. |
| `Tab` | Moves through the popup’s content. Tabbing out of a non-modal popover closes it. |
| `Esc` | Closes the popover and returns focus to the trigger. |

## Accessibility

- `<PopoverTitle />` and `<PopoverDescription />` label and describe the popup for screen readers. Include a title whenever the popup contains more than a sentence.
- Focus moves to the first focusable element when it opens and back to the trigger when it closes. Change this with `initialFocus` and `finalFocus`.
- With reduced motion enabled, the popup fades without scaling.

## API reference

Built on the Base UI popover. Every part accepts the props of the primitive it wraps.

### Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` |  |
| `open` | `boolean` | – |  |
| `onOpenChange` | `(open: boolean, details) => void` | – | details.reason says what caused the change. |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the open or close animation ends. |
| `modal` | `boolean \| "trap-focus"` | `false` | true locks page scroll and outside interaction. trap-focus only traps focus. |
| `handle` | `PopoverHandle<Payload>` | – | Connects detached triggers. |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – |  |

### PopoverTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `openOnHover` | `boolean` | `false` |  |
| `delay` | `number` | `300` | Milliseconds before opening on hover. |
| `closeDelay` | `number` | `0` | Milliseconds before closing after hover ends. |
| `handle` | `PopoverHandle<Payload>` | – |  |
| `payload` | `Payload` | – | Passed to the popup when this trigger opens it. |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="popover-trigger"` | Target the trigger in CSS. |
| `data-popup-open` | Present while its popover is open. |
| `data-pressed` | Present while the trigger is pressed. |
| `data-disabled` | Present when the trigger is disabled. |

### PopoverContent

Renders the portal, the positioner and the popup in one part.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left" \| "inline-start" \| "inline-end"` | `"bottom"` |  |
| `align` | `"start" \| "center" \| "end"` | `"center"` |  |
| `sideOffset` | `number \| (data) => number` | `6` | Gap between the trigger and the popup. |
| `alignOffset` | `number \| (data) => number` | `0` |  |
| `collisionPadding` | `number \| Rect` | `8` | Space kept from the edges of the viewport. |
| `collisionAvoidance` | `CollisionAvoidance` | – | Whether to flip, shift or neither when space runs out. |
| `collisionBoundary` | `Boundary` | – |  |
| `anchor` | `Element \| RefObject \| VirtualElement \| () => Element` | – | Position against something other than the trigger. |
| `sticky` | `boolean` | `false` |  |
| `positionMethod` | `"absolute" \| "fixed"` | `"absolute"` |  |
| `initialFocus` | `boolean \| RefObject \| (type) => HTMLElement \| boolean` | – | Where focus goes when the popover opens. |
| `finalFocus` | `boolean \| RefObject \| (type) => HTMLElement \| boolean` | – | Where focus goes when the popover closes. |
| `portalProps` | `PortalProps` | – | Props for the portal, such as container. |
| `className` | `string \| (state) => string` | – | The popup is w-72 by default. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="popover-content"` | The popup. |
| `data-slot="popover-positioner"` | The element that positions the popup. |
| `data-open` | Present while the popover is open. |
| `data-starting-style` | Present while the popup animates in. |
| `data-ending-style` | Present while the popup animates out. |
| `data-side` | The side the popup ended up on. |
| `data-align` | The alignment the popup ended up with. |
| `data-instant` | Present when the change should not animate. |
| `--transform-origin` | The point the popup scales from, at the trigger. |
| `--available-width` | Space between the trigger and the viewport edge. |
| `--available-height` | Space between the trigger and the viewport edge. The popup’s max height. |
| `--anchor-width` | The trigger’s width. |
| `--anchor-height` | The trigger’s height. |

### PopoverHeader

A plain `<div>` that stacks the title and description.

| Attribute | Description |
| --- | --- |
| `data-slot="popover-header"` | Target the header in CSS. |

### PopoverTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<h2>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="popover-title"` | Labels the popup. |

### PopoverDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="popover-description"` | Describes the popup. |

### PopoverClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="popover-close"` | Closes the popover when pressed. |

### createPopoverHandle

`createPopoverHandle<Payload>()` returns a handle that connects a `<Popover />` to triggers rendered elsewhere. Create it once, outside your component.

---

# Progress

> A bar or ring that shows how far a task has come, eases between updates and slides while the total is unknown.

Docs: https://hextaui.com/docs/progress
Markdown: https://hextaui.com/docs/progress.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/progress.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/progress.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Progress,
  ProgressCircle,
  ProgressLabel,
  ProgressValue,
} from "@/components/ui/progress"
```

```tsx
<Progress value={40}>
  <ProgressLabel>Uploading</ProgressLabel>
  <ProgressValue />
</Progress>

<ProgressCircle value={40} aria-label="Uploading" />
```

`<Progress />` draws its own track and indicator after its children, so a label and value sit on one line above the bar. Each update eases the fill from where it is, so rapid updates read as one smooth motion instead of steps.

## Composition

```text
Progress
├── ProgressLabel
└── ProgressValue

ProgressCircle
└── ProgressValue
```

## Examples

### Sizes

`xs`, `sm`, `default` and `lg` change the bar's thickness. `xs` is the hairline Attachment draws along its bottom edge.

### Status

`variant` colors only the fill or ring, so the track, label and value stay neutral.

### Indeterminate

Pass `value={null}` while the total is unknown. A segment slides across the track, and once a number arrives the fill grows from the start.

### Circle

`<ProgressCircle />` draws the same value as a ring, starting at the top. Children sit in the middle, which fits `<ProgressValue />` at `lg` and `xl`.

### Indeterminate circle

An arc spins around the ring until a value arrives.

### Custom range and format

Set `min` and `max` for any range, `format` for the number, and a function child on `<ProgressValue />` for the text. Give screen readers the same words with `getAriaValueText`.

### Animated value

Render `<NumberFlow />` inside `<ProgressValue />` so only the digits that change spin, in step with the fill.

### Long labels

Long names wrap onto their own lines and the value stays on the end. Rings work as compact status beside each row.

### Without a visible label

Name the bar with `aria-label` when the context already says what is loading.

### Right to left

The fill and the indeterminate slide start from the right. Pass `locale` to format the value in the reader's digits.

## Accessibility

- The root is a `progressbar` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and a formatted `aria-valuetext`. While indeterminate it has no current value.
- `<ProgressLabel />` names the bar. Without one, pass `aria-label`.
- `<ProgressValue />` is hidden from screen readers, since the progressbar already announces the value.
- With reduced motion, the fill jumps to each new value, and the indeterminate bar and ring pulse in place instead of moving.
- Values are formatted in `en-US` unless you pass `locale`, so the server and browser render the same text.

## API reference

Built on the Base UI progress. Every part accepts the props of the primitive it wraps.

### Progress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | – | null makes the bar indeterminate. |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `size` | `"xs" \| "sm" \| "default" \| "lg"` | `"default"` |  |
| `variant` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` |  |
| `format` | `Intl.NumberFormatOptions` | – | Formats the value. Without it, the value shows as a percentage. |
| `locale` | `Intl.LocalesArgument` | `"en-US"` |  |
| `getAriaValueText` | `(formattedValue: string, value: number \| null) => string` | – |  |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="progress"` | The root. |
| `data-size` | The size: xs, sm, default or lg. |
| `data-variant` | The status variant. |
| `data-progressing` | Present while the value is below max. |
| `data-complete` | Present when the value reaches max. |
| `data-indeterminate` | Present when the value is null or not a finite number. |

### ProgressLabel

Names the progressbar. Renders a `<span>` and takes the same state attributes as the root.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="progress-label"` | The label. |

### ProgressValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(formattedValue: string \| null, value: number \| null) => ReactNode` | – | Custom text. Without it, the formatted value shows, or nothing while indeterminate. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="progress-value"` | The value. |

### ProgressTrack

Rendered by `<Progress />` and sized by its `size`. Exported for custom compositions.

| Attribute | Description |
| --- | --- |
| `data-slot="progress-track"` | The track. |
| `--progress-dir` | 1, or -1 in right-to-left, so the indeterminate slide follows the reading direction. |

### ProgressIndicator

The fill. Its width is set inline from the value and eases between updates.

| Attribute | Description |
| --- | --- |
| `data-slot="progress-indicator"` | The fill. |

### ProgressCircle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` | – | null spins an arc. |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `size` | `"sm" \| "default" \| "lg" \| "xl"` | `"default"` |  |
| `variant` | `"default" \| "success" \| "warning" \| "destructive"` | `"default"` |  |
| `locale` | `Intl.LocalesArgument` | `"en-US"` |  |
| `children` | `ReactNode` | – | Shown in the middle of the ring. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="progress-circle"` | The root. |
| `data-size` | The size: sm, default, lg or xl. |
| `data-variant` | The status variant. |
| `data-progressing` | Present while the value is below max. |
| `data-complete` | Present when the value reaches max. |
| `data-indeterminate` | Present when the value is null or not a finite number. |
| `--progress-circle-size` | The ring's width and height. |
| `--progress-stroke` | The ring's stroke width. |

---

# Questionnaire

> A step-by-step form that moves between questions with a sense of direction, shows real progress and answers from the keyboard.

Docs: https://hextaui.com/docs/questionnaire
Markdown: https://hextaui.com/docs/questionnaire.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/questionnaire.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @shadcn/react @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/questionnaire.tsx`, `components/ui/button.tsx`, `components/ui/input.tsx`, `components/ui/kbd.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@/components/ui/questionnaire"
```

```tsx
<Questionnaire onSubmit={handleSubmit}>
  <QuestionnaireProgress />
  <QuestionnaireItem name="role" required>
    <QuestionnaireTitle>What best describes your work?</QuestionnaireTitle>
    <QuestionnaireChoices>
      <QuestionnaireChoice value="design">Design</QuestionnaireChoice>
      <QuestionnaireChoice value="engineering">Engineering</QuestionnaireChoice>
    </QuestionnaireChoices>
  </QuestionnaireItem>
  <QuestionnaireActions>
    <QuestionnairePrevious />
    <QuestionnaireNext />
    <QuestionnaireSubmit />
  </QuestionnaireActions>
</Questionnaire>
```

Answers submit as a regular form, keyed by each item's `name`. Questions move toward the direction you go, the card eases to each question's height, and the progress fills only for questions that were answered or skipped.

## Composition

```text
Questionnaire
├── QuestionnaireProgress
├── QuestionnaireItem
│   ├── QuestionnaireTitle
│   ├── QuestionnaireDescription
│   ├── QuestionnaireChoices
│   │   ├── QuestionnaireChoice
│   │   │   └── QuestionnaireChoiceDescription
│   │   └── QuestionnaireInput
│   └── QuestionnaireError
└── QuestionnaireActions
    ├── QuestionnairePrevious
    ├── QuestionnaireSkip
    ├── QuestionnaireNext
    └── QuestionnaireSubmit
```

## Examples

### Lift transition and bar

`transition="lift"` moves questions up and down like a stack. `variant="bar"` on the progress shows one continuous bar.

### Auto-advance

With `autoAdvance`, picking a single answer moves on after a short pause, so you can answer with `1`–`5` alone. Changing an earlier answer never jumps ahead, and the last question never submits by itself.

### Conditional questions

Disable an item to leave it out. It drops from the progress and the flow until it applies.

### Right to left

The slide follows the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `↑` `↓` | Moves between the answers, including the text field. Moving doesn't pick. |
| `Space` | Picks the focused answer, or toggles it in multiple choice. |
| `Enter` | Continues. On an unpicked single answer it picks it first. Submits on the last question. |
| `←` `→` | Previous or next question, mirrored in right-to-left. Next shakes when an answer is needed. Inside the text field they move the cursor. |
| `Home` `End` | First or last answer. |
| `A` `1` | Picks an answer by its key when shortcuts is set. Key caps brighten once the questionnaire has focus; click anywhere in it to start. |
| `Esc` | Leaves the text field so letter shortcuts work again. |
| `⌘` `Enter` | Submits from anywhere. |

## Accessibility

- Each `QuestionnaireItem` is a `<fieldset>` whose title is its `<legend>`. Inactive questions are hidden and inert, including the one animating out.
- The progress is a `progressbar` that announces “Question 2 of 5”; the segments and spinning number are decorative.
- Errors use `role="alert"` and the invalid answers get `aria-invalid`.
- With reduced motion, questions switch instantly and nothing shakes.

## API reference

### Questionnaire

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `transition` | `"slide" \| "lift"` | `"slide"` |  |
| `autoAdvance` | `boolean` | `false` | Moves on 350ms after a single answer is picked for the first time. |
| `shortcuts` | `"letters" \| "numbers"` | – | Adds a key shortcut to every answer. |
| `item` | `string` | – |  |
| `defaultItem` | `string` | – |  |
| `onItemChange` | `(item: string) => void` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="questionnaire"` | The form, with data-transition. |
| `data-current / data-total` | The current position and number of questions. |
| `data-first / data-last` | Present on the first or last question. |

### QuestionnaireProgress

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"segments" \| "bar"` | `"segments"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="questionnaire-progress-segment"` | One per question, with data-status, data-active and data-invalid. |

### QuestionnaireItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | – | The form field name. |
| `required` | `boolean` | `false` |  |
| `multiple` | `boolean` | `false` | Checkboxes instead of radios. |
| `disabled` | `boolean` | `false` | Leaves the question out of the flow. |
| `onStatusChange` | `(status) => void` | – |  |

| Attribute | Description |
| --- | --- |
| `data-status` | "unanswered", "answered" or "skipped". |
| `data-active` | The current question. |
| `data-invalid` | Needs an answer. |
| `data-leaving` | The question animating out. |

### QuestionnaireChoice

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – |  |
| `defaultChecked` | `boolean` | – |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<label>` |  |

| Attribute | Description |
| --- | --- |
| `data-checked / data-unchecked` | Whether the answer is picked. |
| `data-type` | "radio" or "checkbox". |
| `data-shortcut` | The answer's key. |

### QuestionnaireInput

A free-text answer that sits with the choices. Typing clears the picked choice. Give it a label or `aria-label`.

### Navigation buttons

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `Button variant` | `"ghost", or "default" for Next and Submit` |  |
| `size` | `Button size` | `"default"` |  |

`QuestionnaireNext` and `QuestionnaireSubmit` share a slot, so the last question swaps Next for Submit without moving anything.

---

# Radio group

> Pick one option from a set, with a dot that hands off between choices and cards whose selection ring slides to the new pick.

Docs: https://hextaui.com/docs/radio-group
Markdown: https://hextaui.com/docs/radio-group.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/radio-group.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react cn
```

Copy `components/ui/radio-group.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
```

```tsx
<RadioGroup aria-label="Notify me about" defaultValue="mentions">
  <label className="flex items-center gap-3">
    <RadioGroupItem value="all" />
    All new messages
  </label>
  <label className="flex items-center gap-3">
    <RadioGroupItem value="mentions" />
    Direct messages and mentions
  </label>
</RadioGroup>
```

When the choice changes, the old dot shrinks away as the new one springs in, so the eye follows the pick instead of two things blinking at once. Wrap each item in a `<label>` so the whole row is clickable.

## Composition

```text
RadioGroup
├── RadioGroupItem
└── RadioGroupCard
    ├── RadioGroupCardTitle
    └── RadioGroupCardDescription
```

## Examples

### Cards

With `variant="card"`, use `RadioGroupCard` for options with more to say. The selection ring slides to the new card while its surface fades in.

### Horizontal

Cards can sit in a row or any grid. The ring follows them wherever they are.

### Form

Inside `Field` and `FieldSet`, the group gets a legend, required validation and an error message.

### Disabled and read-only

Disable a single option, or make the whole group `readOnly` to show a value that can't change.

### Controlled

Pass `value` and `onValueChange`. Outside changes animate the same way as clicks.

### Right to left

Radios and cards follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus into the group, onto the picked option or the first one. |
| `↑` `↓` `←` `→` | Moves to the previous or next option and picks it, wrapping at the ends. |
| `Space` | Picks the focused option. |

## Accessibility

- Name the group with `aria-label`, `aria-labelledby` or a `FieldLegend`.
- Each radio has a 36px hit area, and 44px on touch screens, while staying 16px on screen.
- The dot and card ring don't move with reduced motion.

## API reference

### RadioGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "card"` | `"default"` | card adds the sliding selection ring. |
| `value` | `Value` | – |  |
| `defaultValue` | `Value` | – |  |
| `onValueChange` | `(value, details) => void` | – |  |
| `name` | `string` | – |  |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="radio-group"` | The group, with data-variant. |
| `data-slot="radio-group-highlight"` | The ring that slides between cards. |
| `data-disabled` | The group is disabled. |

### RadioGroupItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` | – |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="radio-group-item"` | The radio. |
| `data-checked / data-unchecked` | Whether it's the picked option. |
| `data-disabled / data-readonly` | Present when it can't be changed. |

### RadioGroupCard

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` | – |  |
| `disabled` | `boolean` | `false` |  |
| `radioClassName` | `string` | – | Classes for the radio inside the card. |

A `<label>` with the radio built in. Put `RadioGroupCardTitle` and `RadioGroupCardDescription`, or anything else, inside.

---

# Resizable

> Panels you can drag apart, with a quiet divider that wakes up on hover, sizes that glide on reset or collapse, and layouts that persist.

Docs: https://hextaui.com/docs/resizable
Markdown: https://hextaui.com/docs/resizable.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/resizable.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add react-resizable-panels cn
```

Copy `components/ui/resizable.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@/components/ui/resizable"
```

```tsx
<ResizablePanelGroup>
  <ResizablePanel defaultSize="30%" minSize="20%">Sidebar</ResizablePanel>
  <ResizableHandle />
  <ResizablePanel>Content</ResizablePanel>
</ResizablePanelGroup>
```

Numbers are pixels and strings are percentages, so `defaultSize="30%"` and `minSize={240}` both work. The divider stays a hairline until you reach for it. While you drag, panels follow the pointer exactly; every other change glides, including double-click resets, keyboard steps and collapsing from code.

## Composition

```text
ResizablePanelGroup
├── ResizablePanel
├── ResizableHandle
└── ResizablePanel
```

## Examples

### Collapsible

A `collapsible` panel snaps shut when dragged below its `minSize`. Toggle it from a button with `usePanelRef`; the collapse animates.

### Size readout

`showSize` shows the panel before the divider while you drag or use the keyboard, in `"percent"` or `"pixels"`.

### Remember the layout

`useDefaultLayout` saves sizes to `localStorage` and restores them on the next visit without animating in. Give each panel an `id`.

### Vertical

`orientation="vertical"` stacks panels. Groups nest, as in the demo above.

### Visible grip

`withHandle` keeps the grip showing instead of revealing it on hover.

### Right to left

Panels and arrow keys follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `←` `→` `↑` `↓` | Moves the focused divider by 5% along its group's direction. |
| `Home` `End` | Moves the divider as far as the panels allow. |
| `Enter` | Collapses or expands a collapsible panel. |
| `F6` | Moves to the next divider in the group; Shift goes back. |

## Accessibility

- Each divider is a focusable `separator` that reports the size of the panel before it.
- The size readout is decorative; screen readers get the separator's own value.
- With reduced motion, sizes change instantly and the divider doesn't animate.

## API reference

### ResizablePanelGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `defaultLayout` | `Layout` | – |  |
| `onLayoutChange` | `(layout) => void` | – | Every change, including while dragging. |
| `onLayoutChanged` | `(layout, meta) => void` | – | Once a change settles. |
| `disabled` | `boolean` | `false` |  |
| `groupRef` | `Ref<GroupImperativeHandle>` | – |  |

| Attribute | Description |
| --- | --- |
| `data-slot="resizable-panel-group"` | The group. |
| `data-ready` | Set after mount; sizes animate from then on. |

### ResizablePanel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultSize` | `number \| string` | – |  |
| `minSize` | `number \| string` | – |  |
| `maxSize` | `number \| string` | – |  |
| `collapsible` | `boolean` | `false` |  |
| `collapsedSize` | `number \| string` | `0` |  |
| `onResize` | `(size, id, previous) => void` | – |  |
| `panelRef` | `Ref<PanelImperativeHandle>` | – |  |
| `id` | `string` | – | Needed to remember layouts. |

### ResizableHandle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `withHandle` | `boolean` | `false` | Always show the grip. |
| `showSize` | `boolean \| "percent" \| "pixels"` | `false` |  |
| `disableDoubleClick` | `boolean` | `false` | Stop double-click from resetting the panels. |
| `disabled` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="resizable-handle"` | The divider. |
| `data-separator` | "inactive", "hover", "active", "focus" or "disabled". |
| `data-slot="resizable-handle-grip"` | The grip pill. |

### Hooks

`usePanelRef` and `useGroupRef` give you `collapse`, `expand`, `resize` and `setLayout`. `useDefaultLayout` persists a group's layout.

---

# Scroll area

> Native scrolling with a minimal scrollbar, edges that fade only where there’s more to see, and an optional peek that cuts the last item in half.

Docs: https://hextaui.com/docs/scroll-area
Markdown: https://hextaui.com/docs/scroll-area.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/scroll-area.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/scroll-area.tsx` into your project. Their source is in this page's Markdown.

## Usage

Give the scroll area a fixed height or width. Content beyond it scrolls with the native scroll behavior, and a thin scrollbar appears while you hover or scroll.

```tsx
import { ScrollArea } from "@/components/ui/scroll-area"
```

```tsx
<ScrollArea className="h-72 rounded-lg border">
  <div className="p-4">{/* long content */}</div>
</ScrollArea>
```

## Examples

### Peek

Both lists have the same height. With `peek`, on the right, the box trims itself so the last visible item is cut partway through, which shows there is more to scroll before anyone tries. It never trims the box below half its height.

### Text

Edges fade only where there is more content to scroll to. At the top only the bottom fades, and the fade grows in as you scroll away from an edge.

### Start at the bottom

`viewportRef` gives you the scrolling element. Set its `scrollTop` to start a chat at the latest message, so only the top edge fades.

### Horizontal

Set `scrollbars="horizontal"` and give the content `w-max` so it can grow past the box.

### Both axes

`scrollbars="both"` shows both scrollbars and a corner where they meet, and fades all four edges.

### Dynamic content

Peek and the fades update as items are added or removed. With too few items to scroll, the box keeps its height and nothing fades.

### On a colored surface

The fade is a mask on the content, not an overlay color, so it works on any background.

### Inside a sheet

Inside a flex column, wrap it in an element with `min-h-0 flex-1` and give the scroll area `h-full` so it fills the remaining space.

### Without fade

Turn the edge fades off with `fade={false}`.

### Right to left

Content starts at the right edge, the scrollbar and fades follow the reading direction, and the direction is picked up from the page.

## Keyboard

The viewport joins the tab order only when it has something to scroll. Once focused, it scrolls with the browser’s native keys.

| Key | Action |
| --- | --- |
| `Tab` | Focuses the viewport when its content overflows. |
| `↑` `↓` | Scrolls vertically. |
| `←` `→` | Scrolls horizontally. |
| `Page Up` `Page Down` `Space` | Scrolls by a page. |
| `Home` `End` | Jumps to the start or end. |

## Accessibility

- Give the scroll area an `aria-label` when its purpose isn’t clear from the surrounding content, like the “Messages” label in the chat example.
- The focus ring is drawn on the scroll area itself, so it stays visible above the faded edges.

## API reference

Built on the Base UI scroll area. `ScrollArea` renders the root, viewport, content and scrollbars together.

### ScrollArea

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scrollbars` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` |  |
| `fade` | `boolean` | `true` | Fade the edges that have more content. |
| `peek` | `boolean` | `false` | Trim the height so the last visible item is cut partway. Mark items with data-scroll-area-item to choose which elements count. |
| `viewportRef` | `Ref<HTMLDivElement>` | – | The element that scrolls. |
| `overflowEdgeThreshold` | `number \| { xStart, xEnd, yStart, yEnd }` | `0` | Pixels to scroll before an edge counts as overflowing. |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="scroll-area"` | The root. |
| `data-slot="scroll-area-viewport"` | The element that scrolls. |
| `data-slot="scroll-area-content"` | Wraps your content inside the viewport. |
| `data-peek` | Present when peek is on. |
| `data-peeking` | Present while peek is trimming the height. |
| `data-scrolling` | Present while the user scrolls. |
| `data-has-overflow-x` | Present when content is wider than the viewport. |
| `data-has-overflow-y` | Present when content is taller than the viewport. |
| `data-overflow-y-start` | Present when there is more content above. Matching -y-end, -x-start and -x-end attributes exist for the other edges. |
| `--scroll-area-fade` | Size of the edge fade. Defaults to 2.5rem. |
| `--scroll-area-overflow-y-start` | Distance from the top edge in pixels. Matching -y-end, -x-start and -x-end variables exist. |

### ScrollBar

Rendered for you by `ScrollArea`. Export it only if you compose the Base UI parts yourself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="scroll-area-scrollbar"` | The scrollbar track. |
| `data-slot="scroll-area-thumb"` | The draggable thumb. |
| `data-orientation` | vertical or horizontal. |
| `data-hovering` | Present while the pointer is over the area. |
| `data-scrolling` | Present while the user scrolls. |
| `--scroll-area-thumb-height` | The thumb’s height. |
| `--scroll-area-thumb-width` | The thumb’s width. |

---

# Select

> Pick one or more options from a list that opens on the current value, with typeahead, groups and form support.

Docs: https://hextaui.com/docs/select
Markdown: https://hextaui.com/docs/select.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/select.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/select.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"
```

```tsx
<Select items={fonts} defaultValue="geist">
  <SelectTrigger aria-label="Font">
    <SelectValue />
  </SelectTrigger>
  <SelectContent>
    {fonts.map((font) => (
      <SelectItem key={font.value} value={font.value}>
        {font.label}
      </SelectItem>
    ))}
  </SelectContent>
</Select>
```

The list opens right over the trigger with the current option lined up on top of the value, so your eye never loses its place. Pass `items` so `SelectValue` shows labels instead of raw values. For long lists that need searching, use Combobox.

## Composition

```text
Select
├── SelectTrigger
│   └── SelectValue
└── SelectContent
    ├── SelectGroup
    │   ├── SelectLabel
    │   └── SelectItem
    └── SelectSeparator
```

## Examples

### Sizes

`size` on `SelectTrigger` matches Input and Button heights.

### Groups and long lists

Group options with `SelectGroup` and `SelectLabel`. Long lists fit the screen and show scroll arrows that scroll when you hover them.

### With icons

Put icons in items, and pass a function to `SelectValue` to show the same icon in the trigger.

### Multiple

With `multiple`, the list stays open while you pick, and the value can summarise long selections.

### In a form

Inside `Field`, the trigger gets its label, description and required validation.

### Disabled and invalid

Disable the whole select or single options, and mark it invalid with aria-invalid.

### Below the trigger

`alignItemWithTrigger={false}` opens the list under the trigger like a menu. Touch input does this automatically.

### Right to left

The trigger, list and check follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Space` `Enter` `↓` `↑` | Opens the list from the trigger. |
| `↓` `↑` | Moves between options. |
| `Home` `End` | Moves to the first or last option. |
| `A–Z` | Jumps to the next option that starts with the typed text. |
| `Enter` `Space` | Picks the highlighted option. |
| `Esc` | Closes the list and returns focus to the trigger. |

## Accessibility

- Label the trigger with `FieldLabel` or `aria-label`.
- On touch, the list opens below the trigger instead of over it, so your finger doesn't land on an option.

## API reference

### Select

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value \| Value[] \| null` | – |  |
| `defaultValue` | `Value \| Value[] \| null` | – |  |
| `onValueChange` | `(value, details) => void` | – |  |
| `items` | `Record<string, ReactNode> \| { value, label }[]` | – | Lets SelectValue show labels. |
| `multiple` | `boolean` | `false` |  |
| `name` | `string` | – |  |
| `required` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |
| `open` | `boolean` | – |  |
| `onOpenChange` | `(open, details) => void` | – |  |

### SelectTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="select-trigger"` | The trigger, with data-size. |
| `data-popup-open` | Present while the list is open. |
| `data-placeholder` | Present while nothing is picked. |

### SelectValue

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placeholder` | `ReactNode` | – |  |
| `children` | `ReactNode \| (value) => ReactNode` | – | Format the shown value. |

### SelectContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `alignItemWithTrigger` | `boolean` | `true` | Open over the trigger with the current option lined up. |
| `side` | `"top" \| "bottom" \| …` | `"bottom"` | When not aligned with the trigger. |
| `align` | `"start" \| "center" \| "end"` | `"start"` |  |
| `sideOffset` | `number` | `6` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="select-content"` | The popup. |
| `data-side="none"` | Present while aligned over the trigger. |

### SelectItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `Value` | – |  |
| `disabled` | `boolean` | `false` |  |
| `label` | `string` | – | Text for typeahead. |

| Attribute | Description |
| --- | --- |
| `data-selected` | The picked option. |
| `data-highlighted` | The focused option. |
| `data-disabled` | The option is disabled. |

---

# Separator

> A hairline that divides content horizontally or vertically, with an optional label and a decorative mode for purely visual lines.

Docs: https://hextaui.com/docs/separator
Markdown: https://hextaui.com/docs/separator.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/separator.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react cn
```

Copy `components/ui/separator.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Separator } from "@/components/ui/separator"
```

```tsx
<Separator />
<Separator orientation="vertical" />
<Separator>Or continue with</Separator>
```

The line is one physical pixel thick on every screen, the same hairline as borders, so it lines up with cards and inputs around it. Space it with the parent's `gap` or a margin.

## Examples

### Vertical

With `orientation="vertical"` the line stretches to the height of its flex row. Outside a flex row, give it a height.

### Label

Children sit in the middle of the line, with the line filling the space on both sides.

### Align

`align` moves the label to the `start` or `end`, which suits section and date headers. Icons are sized to the text.

### Vertical label

A vertical separator with a label keeps the text upright and draws the line above and below it.

### Decorative

`decorative` hides a purely visual line from screen readers, so they don't announce a separator between rows that already read well on their own.

### Inline

Use `render` to output a `<span>` where a `<div>` isn't allowed, like inside a paragraph.

### Long content

Long labels wrap and unbroken strings break, while a short stretch of line stays visible on each side.

### Right to left

Start and end follow the reading direction.

## Accessibility

- A plain separator has `role="separator"` and `aria-orientation`, like an `<hr>`.
- With `decorative`, it gets `role="none"` and screen readers skip it.
- A separator with a label has no role. The separator role would make its text presentational, so the label is read as plain text instead.

## API reference

Built on the Base UI Separator. Renders a `<div>` and accepts its attributes.

### Separator

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `decorative` | `boolean` | `false` | Hide the line from screen readers when it is only visual. |
| `children` | `ReactNode` | – | A label drawn in the line. Leave it out for a plain line. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Where the label sits along the line. |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="separator"` | Target separators in CSS. |
| `data-orientation` | "horizontal" or "vertical". |
| `data-content` | Present when the separator has a label. |
| `data-align` | The label's alignment, when there is a label. |
| `data-slot="separator-label"` | The element that wraps the label. |

---

# Sheet

> A panel that slides in from any edge, with swipe-to-dismiss, scroll lock and stacked nesting.

Docs: https://hextaui.com/docs/sheet
Markdown: https://hextaui.com/docs/sheet.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/sheet.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/sheet.tsx`, `components/ui/button.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Sheet,
  SheetBody,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet"
```

```tsx
<Sheet>
  <SheetTrigger render={<Button variant="outline" />}>Open</SheetTrigger>
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Edit profile</SheetTitle>
      <SheetDescription>Make changes to your profile.</SheetDescription>
    </SheetHeader>
    <SheetBody>{/* content */}</SheetBody>
    <SheetFooter>
      <SheetClose render={<Button />}>Save changes</SheetClose>
    </SheetFooter>
  </SheetContent>
</Sheet>
```

## Composition

```text
Sheet
├── SheetTrigger
└── SheetContent
    ├── SheetHeader
    │   ├── SheetTitle
    │   └── SheetDescription
    ├── SheetBody
    └── SheetFooter
        └── SheetClose
```

## Examples

### Sides

Set `side` to slide in from any edge. Each sheet can be swiped back towards its own edge, and the close gesture follows your finger with momentum.

### Long content

`<SheetBody />` scrolls on its own, so the header and footer stay in place however long the content gets.

### Without the close button

Set `showCloseButton={false}` when the footer already has a way out. Escape, the backdrop and swiping still close it.

### Nested

A sheet or alert dialog opened from a sheet layers on top. The parent scales back slightly and each extra layer adds a lighter backdrop, so the stack stays readable. Escape closes only the top layer.

### Controlled

Pass `open` and `onOpenChange` to open it from anywhere, without a trigger.

### Detached triggers

Share one sheet between several triggers with `createSheetHandle`. Each trigger passes a `payload` that the sheet renders through a function child.

### Right to left

With `dir="rtl"`, the right side mirrors to the left edge, slides in from there and swipes out the same way.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` `Space` | On the trigger, opens the sheet and moves focus inside it. |
| `Tab` `Shift + Tab` | Moves between focusable elements. Focus stays inside the sheet. |
| `Esc` | Closes the topmost sheet and returns focus to its trigger. |

## Accessibility

- The sheet is a modal dialog. `<SheetTitle />` labels it and `<SheetDescription />` describes it, so always include a title.
- Page scroll is locked and content behind it is hidden from assistive tech while it is open.
- The close button is labelled “Close”. The handle on the inner edge shows the sheet can be dragged and is hidden from assistive tech.
- With reduced motion enabled, the sheet fades in and out instead of sliding.

## API reference

Built on the Base UI drawer. Every part accepts the props of the primitive it wraps.

### Sheet

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` |  |
| `open` | `boolean` | – |  |
| `onOpenChange` | `(open: boolean, details) => void` | – |  |
| `onOpenChangeComplete` | `(open: boolean) => void` | – | Called after the open or close animation ends. |
| `modal` | `boolean \| "trap-focus"` | `true` |  |
| `disablePointerDismissal` | `boolean` | `false` | Keep it open when the backdrop is clicked. |
| `swipeDirection` | `"up" \| "down" \| "left" \| "right"` | – | Set automatically from the content’s side and direction. |
| `handle` | `SheetHandle<Payload>` | – |  |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – |  |

### SheetTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `handle` | `SheetHandle<Payload>` | – |  |
| `payload` | `Payload` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-trigger"` | Target the trigger in CSS. |
| `data-popup-open` | Present while its sheet is open. |

### SheetContent

Renders the portal, backdrop, viewport and popup, plus the drag handle and close button.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` |  |
| `showCloseButton` | `boolean` | `true` |  |
| `dir` | `"ltr" \| "rtl"` | – | Sets the direction for the sheet. right and left mirror in rtl. |
| `initialFocus` | `boolean \| RefObject \| (type) => HTMLElement \| boolean` | – |  |
| `finalFocus` | `boolean \| RefObject \| (type) => HTMLElement \| boolean` | – |  |
| `className` | `string \| (state) => string` | – | Side sheets are 75% wide, up to 24rem from the sm breakpoint. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-content"` | The sheet panel. |
| `data-side` | The side it opens from. |
| `data-open` | Present while the sheet is open. |
| `data-starting-style` | Present while it animates in. |
| `data-ending-style` | Present while it animates out. |
| `data-swiping` | Present while it is being dragged. |
| `data-swipe-direction` | The direction that dismisses it. |
| `data-nested-drawer-open` | Present while a nested sheet is open on top. |
| `data-slot="sheet-handle"` | The drag handle on the inner edge. |
| `data-slot="sheet-close-button"` | The built-in close button. |
| `--drawer-swipe-movement-x` | Horizontal drag distance. A -y variable exists too. |
| `--nested-drawers` | How many nested sheets are open on top. |

### SheetOverlay

Rendered by `<SheetContent />`. Nested layers get a lighter backdrop.

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-overlay"` | The backdrop. |
| `data-nested` | Present on backdrops of nested layers. |

### SheetHeader, SheetBody, SheetFooter

Plain `<div>` elements that lay out the sheet. The header leaves room for the close button, the body scrolls and takes the remaining height, and the footer stacks its actions on small screens and lines them up at the end from the sm breakpoint.

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-header"` | Title and description. |
| `data-slot="sheet-body"` | Scrollable content. |
| `data-slot="sheet-footer"` | Actions. |

### SheetTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<h2>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-title"` | Labels the sheet. |

### SheetDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<p>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-description"` | Describes the sheet. |

### SheetClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sheet-close"` | Closes the sheet when pressed. |

### createSheetHandle

`createSheetHandle<Payload>()` returns a handle that connects a `<Sheet />` to triggers rendered elsewhere. Create it once, outside your component.

---

# Sidebar

> An app sidebar that collapses to icons or off canvas, stays pinned under your header, and becomes a swipeable sheet on phones.

Docs: https://hextaui.com/docs/sidebar
Markdown: https://hextaui.com/docs/sidebar.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/sidebar.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/sidebar.tsx`, `components/ui/button.tsx`, `components/ui/input.tsx`, `components/ui/sheet.tsx`, `components/ui/skeleton.tsx`, `components/ui/tooltip.tsx`, `hooks/use-composed-ref.ts`, `lib/hotkey.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar"
```

Wrap your layout in `<SidebarProvider />` and put the page in `<SidebarInset />`, after the sidebar.

```tsx
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <AppSidebar />
      <SidebarInset>
        <SidebarTrigger />
        {children}
      </SidebarInset>
    </SidebarProvider>
  )
}
```

```tsx
export function AppSidebar() {
  return (
    <Sidebar>
      <SidebarHeader />
      <SidebarContent>
        <SidebarGroup>
          <SidebarGroupLabel>Application</SidebarGroupLabel>
          <SidebarGroupContent>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton render={<a href="/" />} isActive>
                  <IconHome />
                  <span>Home</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarGroupContent>
        </SidebarGroup>
      </SidebarContent>
      <SidebarFooter />
    </Sidebar>
  )
}
```

## Composition

```text
SidebarProvider
├── Sidebar
│   ├── SidebarHeader
│   ├── SidebarContent
│   │   └── SidebarGroup
│   │       ├── SidebarGroupLabel
│   │       ├── SidebarGroupAction
│   │       └── SidebarGroupContent
│   │           └── SidebarMenu
│   │               └── SidebarMenuItem
│   │                   ├── SidebarMenuButton
│   │                   ├── SidebarMenuAction
│   │                   ├── SidebarMenuBadge
│   │                   └── SidebarMenuSub
│   │                       └── SidebarMenuSubItem
│   │                           └── SidebarMenuSubButton
│   ├── SidebarFooter
│   └── SidebarRail
└── SidebarInset
    └── SidebarTrigger
```

- `SidebarProvider` holds the open state, the keyboard shortcut and the widths.
- `Sidebar` is a column that stays pinned while the page scrolls. Below 768px it becomes a sheet.
- `SidebarHeader` and `SidebarFooter` stay in place. `SidebarContent` scrolls between them.
- `SidebarGroup` is a section with an optional label and action. `SidebarMenu` holds the links.
- `SidebarInset` is the page next to the sidebar.

## Examples

### Variants

`variant` sets the look: a full-height `sidebar`, a `floating` panel, or `inset`, where the page becomes a card on the sidebar color. Switch between them to see the layout animate.

### Collapsible

`offcanvas` slides the sidebar out of view, `icon` shrinks it to its icons and shows each label in a tooltip, and `none` keeps it open. Press `⌘B` or `Ctrl+B` to toggle the sidebar you are working in.

### Collapsible groups and submenus

Wrap a `SidebarGroup` or a `SidebarMenuItem` in a `Collapsible`, render the label or button as the trigger, and nest a `SidebarMenuSub`.

### Right side

Set `side="right"` and place the sidebar after `SidebarInset`. The rail and the mobile sheet follow the side.

### Under a header

The sidebar is sticky, so it starts below anything above it. With a sticky header, set `--sidebar-top` to its height and the sidebar pins below it and fits the rest of the screen.

### Controlled

Pass `open` and `onOpenChange`. The trigger, the rail and the shortcut all go through `onOpenChange`.

### Loading

`SidebarMenuSkeleton` fills a menu while it loads. Widths vary per row and match between server and client.

### Right to left

Set `dir="rtl"` and `side="right"`. Spacing, submenu lines, tooltips and the trigger icon mirror.

## Width

The sidebar is 16rem wide, 18rem on phones and 3rem when collapsed to icons. Override `--sidebar-width`, `--sidebar-width-mobile` and `--sidebar-width-icon` on the provider.

```tsx
<SidebarProvider
  style={
    {
      "--sidebar-width": "20rem",
      "--sidebar-width-mobile": "20rem",
    } as React.CSSProperties
  }
>
```

## Persisting the state

The sidebar has no side effects. To remember whether it was open, save it in `onOpenChange` and read it back into `defaultOpen` when rendering on the server.

```tsx
"use client"

export function Providers({
  defaultOpen,
  children,
}: {
  defaultOpen: boolean
  children: React.ReactNode
}) {
  return (
    <SidebarProvider
      defaultOpen={defaultOpen}
      onOpenChange={(open) => {
        document.cookie = `sidebar_state=${open}; path=/; max-age=604800`
      }}
    >
      {children}
    </SidebarProvider>
  )
}
```

## Keyboard

| Key | Action |
| --- | --- |
| `⌘ + B` `Ctrl + B` | Toggles the sidebar. With several sidebars on a page, the one holding focus responds, otherwise the first. Ignored while typing in a rich text editor. |
| `Tab` `Shift + Tab` | Moves through the links. A collapsed off-canvas sidebar is skipped. |
| `Enter` `Space` | Activates the focused link, button or trigger. |
| `Esc` | Closes the sidebar on phones. |

## Accessibility

- `SidebarTrigger` is labelled “Toggle Sidebar” and exposes `aria-expanded` and `aria-controls`.
- `isActive` sets `aria-current="page"`.
- Collapsing off canvas hides the content from keyboard and screen readers. If focus was inside, it moves to the trigger.
- Collapsed to icons, labels stay in each link's accessible name and show as a tooltip on hover and keyboard focus. Group labels, actions and badges are hidden.
- On phones the sidebar is a modal sheet: focus is trapped, swiping or Esc closes it, and following a link closes it. Links that open a new tab, downloads and modified clicks keep it open.
- With reduced motion enabled, collapsing is instant.

## API reference

### SidebarProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `true` |  |
| `open` | `boolean` | – |  |
| `onOpenChange` | `(open: boolean) => void` | – |  |
| `keyboardShortcut` | `string \| null` | `"mod+b"` | mod is ⌘ on Apple platforms and Ctrl elsewhere. null turns it off. |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-wrapper"` | The layout wrapper. |
| `--sidebar-width` | Expanded width. Defaults to 16rem. |
| `--sidebar-width-mobile` | Width of the phone sheet. Defaults to 18rem. |
| `--sidebar-width-icon` | Width collapsed to icons. Defaults to 3rem. |
| `--sidebar-top` | Where the sidebar pins while scrolling, such as below a sticky header. Defaults to 0px. |

### Sidebar

`className` and other props go to the sidebar container.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"left" \| "right"` | `"left"` |  |
| `variant` | `"sidebar" \| "floating" \| "inset" \| "plain"` | `"sidebar"` | plain drops the surface, the edge line, the scrollbar and the gap between menu items, for a sidebar that sits on the page. |
| `collapsible` | `"offcanvas" \| "icon" \| "none"` | `"offcanvas"` |  |
| `dir` | `"ltr" \| "rtl"` | – | Also sets the direction of the phone sheet. |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar"` | The sidebar, or the sheet on phones. |
| `data-state` | "expanded" or "collapsed". |
| `data-collapsible` | The collapsible mode while collapsed, otherwise "". Style children with group-data-[collapsible=icon]:. |
| `data-variant` | The variant. |
| `data-side` | The side. |
| `data-mobile` | Present on the phone sheet. |
| `data-slot="sidebar-container"` | The panel that slides and resizes. |
| `data-slot="sidebar-inner"` | The surface that holds the content. |

### SidebarTrigger

A ghost icon `Button` that calls `toggleSidebar`. Call `event.preventDefault()` in `onClick` to stop it. Pass children to replace the icon.

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-trigger"` | The trigger. |
| `aria-expanded` | Whether the sidebar is open. |

### SidebarRail

A thin hit area on the sidebar edge that toggles it on click. It is left out of the tab order because the trigger and shortcut cover keyboard users. When the sidebar is off canvas, the rail stays at the screen edge.

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-rail"` | The rail. |

### SidebarInset

A `<main>` that takes the rest of the width. Next to an `inset` sidebar it becomes a rounded card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `React.ReactElement \| (props) => React.ReactElement` | – | Renders a different element. Pass a <div /> when the page already has a <main> landmark. |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-inset"` | The page area. |

### SidebarHeader, SidebarContent, SidebarFooter

Plain `<div>` elements. The content scrolls with a thin scrollbar and soft edge fades.

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-header"` | Top section. |
| `data-slot="sidebar-content"` | Scrollable middle. |
| `data-slot="sidebar-footer"` | Bottom section. |

### SidebarGroup, SidebarGroupContent

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-group"` | A section of the sidebar. |
| `data-slot="sidebar-group-content"` | The group's content. |

### SidebarGroupLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-group-label"` | Slides up and fades when collapsed to icons. |

### SidebarGroupAction

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-group-action"` | Needs an accessible label. |

### SidebarMenu, SidebarMenuItem

A `<ul>` and its `<li>` items.

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-menu"` | The list. |
| `data-slot="sidebar-menu-item"` | An item. group/menu-item for hover styles. |

### SidebarMenuButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | Highlights it and sets aria-current="page". |
| `variant` | `"default" \| "outline"` | `"default"` |  |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` |  |
| `tooltip` | `ReactNode \| TooltipContentProps` | – | Shown while collapsed to icons. Content slides between items as you move along the menu. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-menu-button"` | peer/menu-button for sibling styles. |
| `data-active` | Present while isActive. |
| `data-size` | The size. |

### SidebarMenuAction

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showOnHover` | `boolean` | `false` | Shows it only while the item is hovered or focused, or its menu is open. Always visible on touch screens. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-menu-action"` | Needs an accessible label. |

### SidebarMenuBadge

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-menu-badge"` | A count at the end of the item. |

### SidebarMenuSkeleton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showIcon` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-menu-skeleton"` | Hidden from assistive tech. |

### SidebarMenuSub, SidebarMenuSubItem, SidebarMenuSubButton

A nested list with a line on its leading edge. It folds away when the sidebar collapses to icons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | On SidebarMenuSubButton. |
| `size` | `"sm" \| "md"` | `"md"` | On SidebarMenuSubButton. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<a>` | On SidebarMenuSubButton. |

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-menu-sub"` | The nested list. |
| `data-slot="sidebar-menu-sub-button"` | A nested link. |
| `data-active` | Present while isActive. |

### SidebarInput, SidebarSeparator

A small `Input` on the page background, and a hairline separator.

| Attribute | Description |
| --- | --- |
| `data-slot="sidebar-input"` | The input. |
| `data-slot="sidebar-separator"` | The separator. |

### useSidebar

Reads and controls the nearest sidebar. Throws outside `SidebarProvider`.

```tsx
const {
  state,
  open,
  setOpen,
  openMobile,
  setOpenMobile,
  isMobile,
  toggleSidebar,
} = useSidebar()
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `"expanded" \| "collapsed"` | – |  |
| `open` | `boolean` | – |  |
| `setOpen` | `(open: boolean) => void` | – |  |
| `openMobile` | `boolean` | – |  |
| `setOpenMobile` | `(open: boolean) => void` | – |  |
| `isMobile` | `boolean` | – |  |
| `toggleSidebar` | `() => void` | – | Toggles the sheet on phones, else the sidebar. |

---

# Skeleton

> Placeholders that wait 150ms before showing, take the exact size of the content they wrap, and fade it in without moving anything.

Docs: https://hextaui.com/docs/skeleton
Markdown: https://hextaui.com/docs/skeleton.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/skeleton.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn tw-animate-css
```

Copy `components/ui/skeleton.tsx` into your project. Their source is in this page's Markdown.

## Theme

The shimmer and pulse use two animations from your theme. Add them to your global CSS file once.

```css
@import "tw-animate-css";

@theme {
  --animate-shimmer: shimmer 1.6s ease-in-out infinite;
  --animate-skeleton-pulse: skeleton-pulse 2s ease-in-out infinite;

  @keyframes shimmer {
    from {
      translate: calc(-100% * var(--skeleton-dir, 1)) 0;
    }
    to {
      translate: calc(100% * var(--skeleton-dir, 1)) 0;
    }
  }

  @keyframes skeleton-pulse {
    0%,
    100% {
      opacity: 0;
    }
    50% {
      opacity: 0.5;
    }
  }
}
```

## Usage

Use a skeleton on its own as a sized placeholder, or pass `loading` and wrap the real content so the placeholder takes its exact size.

```tsx
import { Skeleton, SkeletonText } from "@/components/ui/skeleton"
```

```tsx
<Skeleton className="h-4 w-32" />

<Skeleton loading={isLoading}>
  <h3>{user.name}</h3>
</Skeleton>
```

## Examples

### Shapes

On its own, a skeleton is an empty block. Give it a size and radius with classes to match what it stands in for.

### Animations

`animation` picks a sweeping `shimmer`, a soft `pulse`, or `none`.

### Text

`<SkeletonText />` draws one bar per line and follows the parent’s font size and line height, so it fills the same space as the text it replaces. The last line is shorter.

### Wrap real content

With `loading`, the skeleton renders the real content invisibly underneath, so it takes the exact size and nothing shifts when the data arrives. When `loading` turns false, the content fades in.

### Inline

Pass `render={<span />}` to place a skeleton inside a sentence. It sits on the text baseline.

### Fast load

A skeleton stays invisible for its first 150ms, then fades in. Data that arrives sooner never flashes a placeholder.

### Many rows

Skeletons that mount together start their animation together, so a long list reads as one loading area.

### Right to left

In a right-to-left layout the shimmer sweeps from right to left.

## Accessibility

- A skeleton on its own is decorative and hidden from assistive tech, and so is `<SkeletonText />`.
- A skeleton wrapping content sets `aria-busy` while loading. The content underneath is hidden from assistive tech and can’t be focused until it loads.
- Skeletons don’t announce anything. When people need to know what is loading, add a visible label or a status message.
- With reduced motion enabled, skeletons appear right away without shimmer, pulse or fade.

## API reference

### Skeleton

Accepts every attribute of the element it renders.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `animation` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` |  |
| `loading` | `boolean` | – | When set, the skeleton wraps its children: true shows the placeholder, false shows the content. Leave it out for a standalone placeholder. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="skeleton"` | Target skeletons in CSS. |
| `data-animation` | The animation in use. Removed once wrapped content has loaded. |
| `data-loading` | "true" or "false" when the skeleton wraps content. |
| `data-slot="skeleton-content"` | Wraps the real content. Invisible and inert while loading. |
| `--skeleton-dir` | 1, or -1 in right-to-left layouts. Sets the shimmer’s direction. |

### SkeletonText

Accepts every `<div>` attribute.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `number` | `3` | Rounded down and kept between 1 and 50. |
| `animation` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="skeleton-text"` | The container for the lines. |

---

# Slider

> Pick a value or a range by dragging, tapping the track or using the keys, with jumps that glide and an optional value bubble.

Docs: https://hextaui.com/docs/slider
Markdown: https://hextaui.com/docs/slider.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/slider.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/slider.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Slider, SliderLabel, SliderValue } from "@/components/ui/slider"
```

```tsx
<Slider defaultValue={[50]} max={100} step={1} aria-label="Volume" />

<Slider defaultValue={50}>
  <SliderLabel>Volume</SliderLabel>
  <SliderValue />
</Slider>
```

`<Slider />` draws one thumb per value, so a number or a one-item array makes a single slider and two items make a range. Children such as `<SliderLabel />` and `<SliderValue />` sit on one line above the track.

While you drag, the thumb follows the pointer exactly. When the value jumps, from a press on the track, a key or a new controlled value, the thumb and fill glide there in 180ms instead of teleporting.

## Composition

```text
Slider
├── SliderLabel
└── SliderValue
```

## Examples

### Sizes

`sm`, `default` and `lg` scale the thumb and track together.

### Range

Pass two values for a range. Name each thumb with `getAriaLabel`, and keep them apart with `minStepsBetweenValues`. With `draggableRange`, drag anywhere between the thumbs to move both at once; a tap there still moves the nearest thumb.

### Value bubble

`showValue` shows the formatted value above the thumb while it is dragged or focused from the keyboard. Use it instead of a label row, since the bubble rises into the space above the track.

### Steps and format

`step` snaps the value, `largeStep` sets the Page Up and Shift + arrow jump, and `format` formats every number the slider shows or announces.

### Controlled

`onValueChange` fires on every move and `onValueCommitted` once on release, which is the moment to save. Setting the value from outside glides too.

### Vertical

With `orientation="vertical"` the slider fills its parent's height, and Up raises the value.

### With icons

Place icons beside the slider in a flex row. The slider takes the remaining width.

### Disabled

The whole slider dims and ignores pointer and keyboard input.

### Long labels

Long labels wrap, and the value stays on the end.

### Right to left

Inside a right-to-left parent the fill starts from the right and the arrow keys follow it. Pass `locale` for the reader's digits.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves focus to the next thumb. |
| `→` `↑` | Increases the value by one step. → decreases it in right-to-left. |
| `←` `↓` | Decreases the value by one step. ← increases it in right-to-left. |
| `Shift + Arrow` `Page Up` `Page Down` | Moves by largeStep. |
| `Home` | Sets the minimum, or the previous thumb's value in a range. |
| `End` | Sets the maximum, or the next thumb's value in a range. |

## Accessibility

- Each thumb holds a native `input type="range"`, so it is a `slider` with its own value, min and max.
- `<SliderLabel />` names every thumb. Without one, `aria-label` on `<Slider />` is passed to the thumbs, not the wrapper, so the slider is never left unnamed. In a range, use `getAriaLabel` to tell the thumbs apart.
- `<SliderValue />` and the value bubble are not announced on every change; the thumb already reports its value.
- Pressing a thumb doesn't show a focus ring; the arrow keys do. With reduced motion the thumb jumps instead of gliding.
- On touch screens the hit area grows to at least 44px without changing the layout.

## API reference

Built on the Base UI slider. Every part accepts the props of the primitive it wraps.

### Slider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| number[]` | – | The controlled value. One thumb per item. |
| `defaultValue` | `number \| number[]` | – |  |
| `onValueChange` | `(value, eventDetails) => void` | – | Fires on every change while dragging. |
| `onValueCommitted` | `(value, eventDetails) => void` | – | Fires once when a change ends. |
| `min` | `number` | `0` |  |
| `max` | `number` | `100` |  |
| `step` | `number` | `1` |  |
| `largeStep` | `number` | `10` |  |
| `minStepsBetweenValues` | `number` | `0` |  |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `draggableRange` | `boolean` | `false` | In a range, dragging between the thumbs moves them together, keeping the gap. |
| `showValue` | `boolean` | `false` | Shows the value above the thumb while dragging or keyboard-focused. |
| `thumbAlignment` | `"edge" \| "center" \| "edge-client-only"` | `"edge"` | edge keeps the thumb inside the track at min and max. |
| `thumbCollisionBehavior` | `"push" \| "swap" \| "none"` | `"push"` |  |
| `format` | `Intl.NumberFormatOptions` | – |  |
| `locale` | `Intl.LocalesArgument` | `"en-US"` |  |
| `aria-label` | `string` | – | Names the thumbs. |
| `getAriaLabel` | `(index: number) => string` | – | Names each thumb of a range. |
| `getAriaValueText` | `(formattedValue: string, value: number, index: number) => string` | – |  |
| `name` | `string` | – |  |
| `disabled` | `boolean` | `false` |  |
| `className` | `string \| (state) => string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="slider"` | The root. |
| `data-size` | sm, default or lg. |
| `data-jump` | Present for 220ms while the thumb glides to a new value. |
| `data-range-dragging` | Present while the whole range is being dragged. |
| `data-orientation` | horizontal or vertical. |
| `data-dragging` | Present while a pointer is down. |
| `data-disabled` | Present when disabled. |
| `data-invalid` | Present when invalid inside a Field. |
| `--slider-thumb` | The thumb's diameter, set by size. |
| `--slider-track` | The track's thickness, set by size. |
| `data-slot="slider-control"` | The pressable area around the track. |
| `data-slot="slider-track"` | The track. |
| `data-slot="slider-range"` | The fill between the start, or the first thumb, and the last thumb. |
| `data-slot="slider-thumb"` | Each thumb. data-index gives its position. |
| `data-active` | On the thumb that is focused or being dragged. |
| `data-slot="slider-thumb-value"` | The value bubble from showValue. |

### SliderLabel

Names the thumbs and grows to fill the row. Renders a `<div>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="slider-label"` | The label. |

### SliderValue

Shows the formatted values, joined with an en dash in a range. Renders an `<output>`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `(formattedValues: string[], values: number[]) => ReactNode` | – | Custom text. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<output>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="slider-value"` | The value. |
| `data-orientation` | horizontal or vertical. |
| `data-dragging` | Present while a pointer is down. |
| `data-disabled` | Present when disabled. |
| `data-invalid` | Present when invalid inside a Field. |

---

# Spinner

> A loading indicator with Apple-style ticks or a breathing ring that can wait before showing and stay long enough not to flicker.

Docs: https://hextaui.com/docs/spinner
Markdown: https://hextaui.com/docs/spinner.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/spinner.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add class-variance-authority cn
```

Copy `components/ui/spinner.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Spinner } from "@/components/ui/spinner"
```

```tsx
<Spinner />
<Spinner variant="ring" size="lg" />
<Spinner loading={isFetching} />
```

The default is the eight-spoke indicator from Apple platforms. `variant="ring"` spins while its arc grows and shrinks, so it reads as working rather than stuck. Both are drawn in the current text color.

## Examples

### Without flicker

Pass `loading` and the spinner waits `delay` (150ms) before showing, so fast loads never flash it, then stays at least `minDuration` (400ms) once it's visible.

### Sizes

`sm`, `default`, `lg` and `xl` for both variants.

### Inline

Next to text, mark the spinner `aria-hidden` so the words do the talking. On its own, it announces its `label`.

### In buttons

Button and Command use this spinner for their loading states, sized to the button's icons.

## Accessibility

- On its own, the spinner is a `status` named by `label` (“Loading”).
- With `aria-hidden`, it drops its role, for use beside visible text or inside a busy button.
- With reduced motion, it gently pulses instead of spinning, so it still shows that something is happening.

## API reference

### Spinner

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"ticks" \| "ring"` | `"ticks"` |  |
| `size` | `"sm" \| "default" \| "lg" \| "xl" \| null` | `"default"` | null leaves sizing to the parent. |
| `label` | `string` | `"Loading"` |  |
| `loading` | `boolean` | – | Turns on delayed showing. Leave it out to always show. |
| `delay` | `number` | `150` |  |
| `minDuration` | `number` | `400` |  |
| `animated` | `boolean` | `true` | Pause the animation without hiding it. |

| Attribute | Description |
| --- | --- |
| `data-slot="spinner"` | The SVG, with data-variant. |

### useDelayedLoading

```tsx
const visible = useDelayedLoading(isFetching, { delay: 150, minDuration: 400 })
```

The same timing as a hook, for skeletons, overlays or anything else that shouldn't flash. See the [useDelayedLoading guide](https://hextaui.com/docs/use-delayed-loading).

---

# Switch

> An on/off toggle you can tap, press or drag, with a thumb that stretches under your finger and an optional pending state for saves.

Docs: https://hextaui.com/docs/switch
Markdown: https://hextaui.com/docs/switch.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/switch.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/switch.tsx`, `components/ui/spinner.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Switch } from "@/components/ui/switch"
```

```tsx
<label className="flex items-center gap-3">
  <Switch defaultChecked />
  Wi-Fi
</label>
```

Press and the thumb stretches toward the other side before springing across, so you feel the press land. You can also grab the thumb and drag it: past the middle it flips, short of it it snaps back.

## Examples

### iOS

`variant="ios"` uses a taller track, a capsule thumb and green when on. Press, drag and saving work the same.

### Saving

Return a promise from `onCheckedChange` and the switch flips right away with a spinner in the thumb. If it rejects, the switch flips back and shakes.

### On and off marks

`icons` adds a check and a ring to the track, so the state doesn't rely on color.

### Sizes

`sm`, `default` and `lg`.

### In a field

With `Field`, the label and description are linked to the switch.

### Disabled and read-only

`readOnly` keeps the value visible and focusable but won't change it.

### Controlled

Pass `checked` and `onCheckedChange`.

### Right to left

The thumb starts on the right and slides left, and dragging follows.

## Keyboard

| Key | Action |
| --- | --- |
| `Space` `Enter` | Turns the focused switch on or off. |

## Accessibility

- The switch is a `switch` role named by its label. Wrap it in a `<label>` or use `Field`.
- While saving, it's `aria-busy` and ignores new presses.
- The hit area is larger than the switch, and larger again on touch.
- With reduced motion, the thumb moves instantly and nothing shakes.

## API reference

### Switch

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | – |  |
| `defaultChecked` | `boolean` | `false` |  |
| `onCheckedChange` | `(checked, details) => void \| Promise` | – | Return a promise to show the saving state. On rejection an uncontrolled switch flips back. |
| `variant` | `"default" \| "ios"` | `"default"` |  |
| `size` | `"sm" \| "default" \| "lg"` | `"default"` |  |
| `icons` | `boolean` | `false` | Show on and off marks in the track. |
| `name` | `string` | – |  |
| `value` | `string` | – |  |
| `disabled` | `boolean` | `false` |  |
| `readOnly` | `boolean` | `false` |  |
| `required` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<span>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="switch"` | The track, with data-size and data-variant. |
| `data-slot="switch-thumb"` | The thumb. |
| `data-checked / data-unchecked` | Whether the switch is on. |
| `data-dragging` | Present while the thumb is being dragged. |
| `data-pending` | Present while a returned promise is pending. |
| `--switch-w / --switch-h / --switch-thumb / --switch-thumb-w` | Track and thumb sizes, set by size. |

---

# Table

> A responsive table with a surface style, wrapping or compact cells, sticky headers, pinned columns and scroll hints.

Docs: https://hextaui.com/docs/table
Markdown: https://hextaui.com/docs/table.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/table.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add class-variance-authority cn
```

Copy `components/ui/table.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"
```

```tsx
<Table variant="surface">
  <TableHeader>
    <TableRow>
      <TableHead>Invoice</TableHead>
      <TableHead align="end">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableHead scope="row">INV-0418</TableHead>
      <TableCell align="end">$2,400.00</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

Use `<TableHead scope="row">` for the cell that names each row. It reads as the row's header to screen readers and gets a stronger text color. For sorting, filtering and selection, build on `<DataTable />`.

## Composition

```text
Table
├── TableCaption
├── TableHeader
│   └── TableRow
│       └── TableHead
├── TableBody
│   └── TableRow
│       └── TableCell
└── TableFooter
    └── TableRow
        └── TableCell
```

## Examples

### Default

The default variant has no surface, just hairlines between rows, for tables that sit inside a card or a page section. `<TableCaption />` describes the table below it.

### Compact

`size="sm"` tightens row height and padding for dense data.

### Wrapping text

Cells stay on one line by default, which suits data. `wrap` lets them wrap and aligns rows to the top, for prose like glossaries or API references. Pair it with `table-fixed` and column widths.

### Wide tables

Tables wider than their container scroll sideways. Soft fades show there's more on either side, and the scroll area becomes focusable so keyboard users can scroll it with the arrow keys. Turn the fades off with `scrollFade={false}`.

### Pinned column

`pinned="start"` keeps the first column in view while the rest scrolls, and `pinnedEdge` shows a shadow once content slides under it.

### Sticky header

`stickyHeader` keeps the header in view in a height-limited table, and adds a hairline under it once rows scroll beneath.

### Right to left

Alignment, pinned columns and scroll fades follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Focuses the scroll area when the table overflows, then the links and buttons inside it. |
| `←` `→` | Scrolls a focused, overflowing table sideways. |
| `↑` `↓` | Scrolls a focused table with a sticky header up and down. |

## Accessibility

- The parts render native table elements, so screen readers announce rows, columns and headers without extra roles.
- Mark the cell that names a row with `<TableHead scope="row">` so each value is read with its row and column.
- The scroll area only joins the tab order while it overflows, so tables that fit don't add an extra stop.

## API reference

Every part renders its native element and accepts its attributes.

### Table

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "surface"` | `"default"` | surface adds a rounded hairline frame and a muted header band. |
| `size` | `"sm" \| "default"` | `"default"` |  |
| `wrap` | `boolean` | `false` | Let cell text wrap and align rows to the top. |
| `scrollFade` | `boolean` | `true` | Fade the edges that have more content to scroll to. Skipped when columns are pinned. |
| `stickyHeader` | `boolean` | `false` | Keep the header in view. Give the container a max height through containerClassName. |
| `containerClassName` | `string` | – | Classes for the scroll container. |
| `containerRef` | `Ref<HTMLDivElement>` | – | Ref to the scroll container. |

| Attribute | Description |
| --- | --- |
| `data-slot="table-frame"` | The outer frame, with data-variant, data-size and data-wrap. |
| `data-slot="table-container"` | The scroll container. |
| `data-overflowing` | Present on the container while its content overflows. It's focusable then. |
| `data-scrolled-start / data-scrolled-end` | Present while there's content hidden before or after the visible area. |
| `data-scrolled-top` | Present once a sticky-header table has scrolled. |
| `--table-bg` | Row background. Follows a surrounding card or popover. |
| `--table-head-bg` | Header band background in the surface variant. |
| `--table-cell-px / --table-cell-py` | Cell padding. Set by size. |

### TableHead

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `scope` | `"col" \| "row"` | – | Use row for the cell that names a row. Inside the body it gets cell padding and foreground text. |
| `align` | `"start" \| "center" \| "end"` | `"start"` | end also switches to tabular numbers so digits line up. |
| `pinned` | `"start" \| "end"` | – | Keep the column in view while the table scrolls sideways. Set the same value on its header and every cell. |
| `pinnedEdge` | `boolean` | `false` | Draw a soft shadow on the inner edge of the last pinned column while content is hidden behind it. |

| Attribute | Description |
| --- | --- |
| `data-slot="table-head"` | Target header cells in CSS. |
| `data-align` | The alignment. |
| `data-pinned` | The pinned side. |

### TableCell

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | `"start"` | end also switches to tabular numbers so digits line up. |
| `pinned` | `"start" \| "end"` | – | Keep the column in view while the table scrolls sideways. Set the same value on its header and every cell. |
| `pinnedEdge` | `boolean` | `false` | Draw a soft shadow on the inner edge of the last pinned column while content is hidden behind it. |

| Attribute | Description |
| --- | --- |
| `data-slot="table-cell"` | Target cells in CSS. |
| `data-align` | The alignment. |
| `data-pinned` | The pinned side. |

### TableRow

| Attribute | Description |
| --- | --- |
| `data-slot="table-row"` | Target rows in CSS. |
| `data-state="selected"` | Set it to highlight a selected row. |

### TableHeader, TableBody, TableFooter and TableCaption

| Attribute | Description |
| --- | --- |
| `data-slot="table-header"` | The thead. |
| `data-slot="table-body"` | The tbody. |
| `data-slot="table-footer"` | The tfoot, on the header band color. |
| `data-slot="table-caption"` | Below the table. In the surface variant it sits inside the frame. |

---

# Tabs

> Switch between views with an indicator that slides to the active tab, as a segmented control or an underline, and lists that scroll when they overflow.

Docs: https://hextaui.com/docs/tabs
Markdown: https://hextaui.com/docs/tabs.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/tabs.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/tabs.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
```

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="analytics">Analytics</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">…</TabsContent>
  <TabsContent value="analytics">…</TabsContent>
</Tabs>
```

One indicator slides to the active tab and resizes to fit it, while the content switches instantly so frequent switching never waits on an animation. The indicator is placed before the page hydrates, so it never jumps in on load.

## Composition

```text
Tabs
├── TabsList
│   └── TabsTrigger
└── TabsContent
```

## Examples

### Underline

`variant="line"` on `TabsList` slides an underline instead of a pill.

### Many tabs

When tabs don't fit, the list scrolls sideways, fades the edges with more to see, and scrolls the active or focused tab into view.

### Many tabs, segmented

The pill style scrolls the same way, keeping its track while the picked tab stays in view.

### Icons and counts

Put icons and badges inside triggers.

### Vertical

`orientation="vertical"` stacks the tabs; the underline moves to the side.

### Disabled

Disabled tabs are skipped by the keyboard.

### Controlled

Pass `value` and `onValueChange`. Changes from outside slide the indicator too.

### Right to left

Tabs, arrow keys and the indicator follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves into the list on the active tab, then into the panel. |
| `←` `→` | Moves between tabs, wrapping at the ends. ↑ and ↓ when vertical. |
| `Home` `End` | Moves to the first or last tab. |
| `Enter` `Space` | Opens the focused tab. Set activateOnFocus on TabsList to open tabs as focus moves. |

## Accessibility

- The list is a `tablist`; each trigger is a `tab` that controls its `tabpanel`.
- Panels are focusable, so keyboard users can reach content that has no links or buttons.
- With reduced motion, the indicator jumps instead of sliding.

## API reference

### Tabs

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | – |  |
| `defaultValue` | `any` | `0` |  |
| `onValueChange` | `(value, details) => void` | – |  |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |

| Attribute | Description |
| --- | --- |
| `data-activation-direction` | "left", "right", "up" or "down": where the new tab is relative to the old one. |

### TabsList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "line"` | `"default"` |  |
| `activateOnFocus` | `boolean` | `false` |  |
| `loopFocus` | `boolean` | `true` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="tabs-indicator"` | The sliding pill or underline. |
| `data-scrolled-start / data-scrolled-end` | Present when the list can scroll that way. |
| `--active-tab-left / --active-tab-width` | Position and size of the active tab, also -top and -height. |

### TabsTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | – |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-active` | The open tab. |
| `data-disabled` | The tab is disabled. |

### TabsContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `any` | – |  |
| `keepMounted` | `boolean` | `false` | Keep the panel in the DOM while hidden. |

---

# Textarea

> Multi-line text that grows smoothly with what you write between a minimum and maximum number of rows, with counters, validation and a submit shortcut.

Docs: https://hextaui.com/docs/textarea
Markdown: https://hextaui.com/docs/textarea.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/textarea.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/textarea.tsx`, `components/ui/input.tsx`, `components/ui/number-flow.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Textarea } from "@/components/ui/textarea"
```

```tsx
<Textarea placeholder="Write something…" />
```

The box grows with your text, easing to each new line instead of jumping, from `minRows` up to `maxRows`, then scrolls. Typing is never delayed by the animation.

## Examples

### Send with a shortcut

`submitOnShortcut` submits the form with ⌘ + Enter or Ctrl + Enter. Enter on its own still starts a new line.

### Character count

With `maxLength` inside a `Field`, `FieldCounter` counts as you type and nudges when you hit the limit.

### Rows

`minRows` and `maxRows` set where growing starts and stops.

### Fixed size

`autoResize={false}` keeps a fixed height with a vertical resize handle.

### States

Disabled, read-only and invalid. Invalid textareas shake when a form submit fails.

### Right to left

Text, placeholder and caret follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Enter` | Starts a new line. |
| `⌘` `Enter` | Submits the form, with submitOnShortcut. Ctrl + Enter on Windows and Linux. |

## Accessibility

- Label it with `FieldLabel` or `aria-label`.
- On touch screens the text is at least 16px, so iOS doesn't zoom in when it's focused.
- The shortcut waits while an input method is composing, so confirming a Japanese or Chinese word never sends the message.
- With reduced motion, the box resizes instantly.

## API reference

### Textarea

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoResize` | `boolean` | `true` | Grow with the text instead of a fixed height. |
| `minRows` | `number` | `3` |  |
| `maxRows` | `number` | `10` |  |
| `submitOnShortcut` | `boolean` | `false` | Submit the parent form with ⌘/Ctrl + Enter. |
| `shake` | `boolean` | `true` | Shake when a form submit finds it invalid. |

| Attribute | Description |
| --- | --- |
| `data-slot="textarea"` | The textarea. |
| `data-autoresize` | Present when it grows with its text. |
| `--textarea-min-rows / --textarea-max-rows` | Set from minRows and maxRows. |

---

# Toast

> Brief messages that stack neatly, expand on hover, swipe away, and turn a loading state into success or error in place.

Docs: https://hextaui.com/docs/toast
Markdown: https://hextaui.com/docs/toast.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/toast.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react cn
```

Copy `components/ui/toast.tsx`, `components/ui/button.tsx`, `components/ui/spinner.tsx` into your project. Their source is in this page's Markdown.

## Usage

Add `<Toaster />` once, near the root of your app.

```tsx
import { Toaster } from "@/components/ui/toast"

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  )
}
```

Then call `toast` from anywhere, including outside React components.

```tsx
import { toast } from "@/components/ui/toast"

toast("Event created", { description: "Sunday at 9:00 AM" })
toast.success("Payment received")
toast.promise(save(), { loading: "Saving…", success: "Saved", error: "Couldn't save" })
```

Toasts stack into a neat pile with the newest in front. Hover or focus the pile to fan it out; every timer pauses while you read. Swipe a toast toward its edge to dismiss it.

## Examples

### Types

Every toast uses the same calm surface; only the icon carries the color.

### Promise

`toast.promise` shows a spinner, then turns into a success or error toast in place, with the icon popping in as it changes.

### Action

Pass `action` for a button such as Undo. Clicking it also dismisses the toast.

### Update in place

Keep the id from `toast.loading` and change it with `toast.update`, including its type.

### No duplicates

Give a toast an `id` and calling it again updates the existing one instead of stacking a copy.

## Keyboard

| Key | Action |
| --- | --- |
| `F6` | Moves focus into the toasts and fans them out. |
| `Tab` | Moves between toast actions and close buttons. |
| `Esc` | Dismisses the focused toast. |

## Accessibility

- Toasts are announced politely; `toast.error` is announced right away.
- Timers pause while the pointer or focus is on the toasts, so nobody has to race a countdown.
- Close buttons appear on hover and focus, and are always visible on touch screens.
- With reduced motion, toasts fade instead of sliding.

## API reference

### Toaster

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"` | Phones always use the full width. |
| `limit` | `number` | `3` | Toasts shown at once; older ones fade out. |
| `timeout` | `number` | `5000` | Default time on screen, in ms. |

| Attribute | Description |
| --- | --- |
| `data-slot="toaster"` | The viewport, with data-position. |
| `data-slot="toast"` | Each toast, with data-type, data-expanded and data-swiping. |

### toast()

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `description` | `ReactNode` | – |  |
| `action` | `{ label: ReactNode; onClick?: (event) => void }` | – |  |
| `id` | `string` | – | Reuse to update instead of duplicating. |
| `timeout` | `number` | – | Defaults to the Toaster timeout. Long messages stay up longer, about 250 words a minute. |
| `priority` | `"low" \| "high"` | `"low"` |  |
| `onClose` | `() => void` | – |  |
| `onRemove` | `() => void` | – |  |

Also `toast.success`, `toast.error`, `toast.warning`, `toast.info`, `toast.loading`, `toast.promise`, `toast.update` and `toast.dismiss`. Each returns or takes the toast's id.

---

# Toggle

> A button that stays on or off, with a fill that settles in when pressed, a clear hover-to-on step and icons that can fill with the state.

Docs: https://hextaui.com/docs/toggle
Markdown: https://hextaui.com/docs/toggle.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/toggle.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/toggle.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { Toggle } from "@/components/ui/toggle"
```

```tsx
<Toggle aria-label="Bold">
  <IconBold />
</Toggle>
```

Hovering an off toggle shows a light tint; turning it on settles a stronger fill into place and brings the label to full contrast, so on never looks like hover.

## Examples

### Outline

`variant="outline"` adds a border and a surface, for toggles that sit on their own.

### With text

Icons and labels sit side by side. Toggles with visible text don't need an aria-label.

### Filled when on

Add `group-data-pressed/toggle:fill-current` to an outline icon and it fills in as the toggle turns on.

### Sizes

`sm`, `default` and `lg`. Icon-only toggles stay square.

### Disabled

A disabled toggle keeps showing whether it's on, but can't be pressed or focused.

### Controlled

Pass `pressed` and `onPressedChange`. The label stays the same while the icon follows the state.

### Right to left

Icons lead the label from the right.

## Keyboard

| Key | Action |
| --- | --- |
| `Space` `Enter` | Turns the focused toggle on or off. |
| `Tab` | Moves focus to the next toggle. |

## Accessibility

- The toggle is a `button` with `aria-pressed`, so screen readers announce whether it's on.
- Give icon-only toggles an `aria-label` that names the action ("Mute microphone") and keep it the same in both states. Changing it as well as the pressed state reads as a double negative.
- On touch screens the hit area grows to at least 44px, except inside a toggle group where neighbours would overlap.
- With reduced motion, nothing scales; the fill only fades.

## API reference

### Toggle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "outline"` | `"default"` |  |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` |  |
| `pressed` | `boolean` | – |  |
| `defaultPressed` | `boolean` | `false` |  |
| `onPressedChange` | `(pressed, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |
| `value` | `string` | – | Identifies the toggle inside a toggle group. |
| `className` | `string \| (state) => string` | – |  |
| `nativeButton` | `boolean` | `true` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="toggle"` | The button, with data-variant and data-size. |
| `data-pressed` | Present when the toggle is on. |
| `data-disabled` | Present when the toggle is disabled. |

---

# Toggle group

> A row of toggles for one choice or many, with a fill that slides to the picked item, joined or spaced items and arrow-key focus.

Docs: https://hextaui.com/docs/toggle-group
Markdown: https://hextaui.com/docs/toggle-group.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/toggle-group.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react class-variance-authority cn
```

Copy `components/ui/toggle-group.tsx`, `components/ui/toggle.tsx`, `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
```

```tsx
<ToggleGroup aria-label="Date range" defaultValue={["week"]}>
  <ToggleGroupItem value="day">Day</ToggleGroupItem>
  <ToggleGroupItem value="week">Week</ToggleGroupItem>
  <ToggleGroupItem value="month">Month</ToggleGroupItem>
</ToggleGroup>
```

When one item can be on at a time, a single fill slides to the picked item and takes its shape, so the group reads as one control. With `multiple`, each item fills on its own. The fill is placed before the first paint, so it never slides in on load.

## Composition

```text
ToggleGroup
└── ToggleGroupItem
```

## Examples

### Outline

`variant="outline"` joins the items into one bordered control.

### Multiple

`multiple` lets any number of items be on, like text formatting.

### Sizes

`size` on the group sets every item: `sm`, `default` or `lg`.

### Spacing

`spacing` puts a gap between items on the spacing scale. Outline items with a gap keep their own borders and fills.

### Icons and labels

Put an icon before the label. Icon-only items need an aria-label.

### Vertical

`orientation="vertical"` stacks the items and moves focus with ↑ and ↓.

### Disabled

Disable one item, or the whole group with `disabled`. Disabled items are skipped by the keyboard.

### Controlled

Pass `value` and `onValueChange`. Ignoring the empty value keeps one item on, so pressing the picked item again does nothing.

### Right to left

Item order, joined corners, the sliding fill and arrow keys follow the reading direction.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Moves into the group on the last focused item, then out of it. |
| `←` `→` | Moves between items, wrapping at the ends. ↑ and ↓ when vertical. |
| `Home` `End` | Moves to the first or last item. |
| `Enter` `Space` | Turns the focused item on or off. |

## Accessibility

- The group has the `group` role; give it an `aria-label`. Each item is a button with `aria-pressed`.
- Only one item is in the tab order, so the group is a single Tab stop and arrow keys move inside it.
- Without `multiple`, pressing the picked item turns it off. Control the value to keep one item on.
- With reduced motion, the fill fades instead of sliding.

## API reference

### ToggleGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string[]` | – |  |
| `defaultValue` | `string[]` | – |  |
| `onValueChange` | `(value: string[], details) => void` | – |  |
| `multiple` | `boolean` | `false` |  |
| `variant` | `"default" \| "outline"` | `"default"` | Sets every item's variant. |
| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Sets every item's size. |
| `spacing` | `0 \| 0.5 \| 1 \| 1.5 \| 2 \| 2.5 \| 3 \| 4 \| 5 \| 6 \| 8` | `0` | Gap between items on the spacing scale. 0 joins outline items. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
| `loopFocus` | `boolean` | `true` |  |
| `disabled` | `boolean` | `false` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="toggle-group"` | The root. |
| `data-slot="toggle-group-indicator"` | The sliding fill, rendered without multiple. data-visible when an item is on. |
| `data-variant / data-size / data-spacing` | The group's variant, size and spacing. |
| `data-orientation` | "horizontal" or "vertical". |
| `data-multiple` | Present when many items can be on. |
| `data-disabled` | Present when the group is disabled. |

### ToggleGroupItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Identifies the item in the group's value. |
| `disabled` | `boolean` | `false` |  |
| `variant` | `"default" \| "outline"` | – | Used when the group sets none. |
| `size` | `"default" \| "sm" \| "lg"` | – | Used when the group sets none. |
| `nativeButton` | `boolean` | `true` |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="toggle-group-item"` | Each item. |
| `data-pressed` | The item is on. |
| `data-disabled` | The item is disabled. |
| `data-variant / data-size` | The item's resolved variant and size. |

---

# Tooltip

> A short hint on hover or keyboard focus that opens after a brief rest, switches instantly between neighbours and shows shortcuts.

Docs: https://hextaui.com/docs/tooltip
Markdown: https://hextaui.com/docs/tooltip.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/tooltip.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react cn
```

Copy `components/ui/tooltip.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@/components/ui/tooltip"
```

```tsx
<Tooltip>
  <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="Undo" />}>
    <IconArrowBackUp />
  </TooltipTrigger>
  <TooltipContent>Undo</TooltipContent>
</Tooltip>
```

A tooltip opens after a short rest on the trigger, or right away when the trigger gets keyboard focus. Once one is showing, its neighbours open instantly and without animation, so scanning a toolbar feels like reading labels rather than waiting for each one.

That instant switching works between tooltips that share a `TooltipProvider`. Wrap your app (or a toolbar) in one to share the delay. A tooltip without a provider still works on its own with the same defaults.

```tsx
<TooltipProvider>
  <App />
</TooltipProvider>
```

## Composition

```text
TooltipProvider
└── Tooltip
    ├── TooltipTrigger
    └── TooltipContent

TooltipGroup
└── TooltipTrigger
```

## Examples

### Sides

Set `side` on `TooltipContent`. Logical sides follow the reading direction, and the tooltip flips when there isn’t room.

### With an arrow

`arrow` adds a pointer that stays on the trigger even when the tooltip shifts to fit the screen.

### Keyboard shortcut

Put a `Kbd` or `KbdGroup` after the label. It picks up the tooltip’s colors and sits at the end, showing ⌘ on Apple devices and Ctrl elsewhere.

### Toolbar

Rest on one button, then slide along the group. Tooltips under one `TooltipProvider` swap instantly while you move between them.

### Disabled

A disabled button can still explain why with `focusableWhenDisabled`, which keeps it hoverable and in the tab order. `disabled` on `Tooltip` turns the tooltip off.

### Long content

Text wraps at a comfortable width and never runs past the screen edge, even long URLs.

### Controlled

Pass `open` and `onOpenChange` to drive the tooltip yourself. The reason tells you what opened or closed it.

### One tooltip, many triggers

Create a handle with `createTooltipHandle` and pass a `payload` from each trigger to share a single tooltip.

### Right to left

Inside `dir="rtl"`, `inline-end` opens on the left and the shortcut moves to the other end.

## Keyboard

| Key | Action |
| --- | --- |
| `Tab` | Focusing the trigger from the keyboard opens its tooltip right away. |
| `Esc` | Closes the tooltip and keeps focus on the trigger. |
| `Enter` `Space` | Activates the trigger and closes the tooltip, so it doesn’t cover what happens next. |

## Accessibility

- A tooltip is a visual hint, not a label. Give icon-only triggers an `aria-label` that matches the tooltip text.
- Nothing opens on touch, and a tap only does what the trigger does. Don’t put anything in a tooltip that people need; use a popover for that.
- Pointer users can move onto the tooltip to read or select it without it closing.
- With reduced motion on, the tooltip fades without scaling.

## API reference

Built on the Base UI tooltip. Every part accepts the props of the primitive it wraps.

### TooltipProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `300` | Milliseconds to rest on a trigger before opening. |
| `closeDelay` | `number` | `0` | Milliseconds before closing after leaving. |
| `timeout` | `number` | `400` | How long after one closes that the next opens instantly. |

### Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | – |  |
| `defaultOpen` | `boolean` | `false` |  |
| `onOpenChange` | `(open, details) => void` | – |  |
| `onOpenChangeComplete` | `(open) => void` | – | Called after the open or close animation. |
| `disabled` | `boolean` | `false` | Turns the tooltip off. |
| `disableHoverablePopup` | `boolean` | `false` | Close as soon as the pointer leaves the trigger. |
| `trackCursorAxis` | `"none" \| "x" \| "y" \| "both"` | `"none"` |  |
| `handle` | `TooltipHandle<Payload>` | – | From createTooltipHandle. |
| `children` | `ReactNode \| ({ payload }) => ReactNode` | – |  |

### TooltipTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | – | Overrides the provider delay for this trigger. |
| `closeDelay` | `number` | – |  |
| `closeOnClick` | `boolean` | `true` |  |
| `disabled` | `boolean` | `false` | Stops this trigger opening the tooltip. The element stays enabled. |
| `handle` | `TooltipHandle<Payload>` | – |  |
| `payload` | `Payload` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<button>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="tooltip-trigger"` | The trigger. |
| `data-popup-open` | Present while its tooltip is open. |
| `data-trigger-disabled` | Present when the trigger can’t open the tooltip. |

### TooltipContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"` | `"top"` |  |
| `align` | `"start" \| "center" \| "end"` | `"center"` |  |
| `sideOffset` | `number \| (data) => number` | `6, or 8 with arrow` |  |
| `alignOffset` | `number` | `0` |  |
| `arrow` | `boolean` | `false` |  |
| `collisionPadding` | `number` | `8` |  |
| `arrowPadding` | `number` | `8` |  |
| `portalProps` | `TooltipPortal props` | – | Such as container or keepMounted. |

| Attribute | Description |
| --- | --- |
| `data-slot="tooltip-content"` | The popup. |
| `data-slot="tooltip-positioner"` | The positioning wrapper around the popup. |
| `data-side` | The side it opened on after flipping. |
| `data-align` | The alignment. |
| `data-instant` | "delay", "focus" or "dismiss" when it opens or closes without animation. |
| `data-starting-style` | Present while it animates in. |
| `data-ending-style` | Present while it animates out. |
| `--available-width` | Room between the trigger and the screen edge. |
| `--transform-origin` | The point the tooltip scales from. |

### TooltipArrow

Rendered for you by `arrow`. Use it directly only when composing your own content part.

| Attribute | Description |
| --- | --- |
| `data-slot="tooltip-arrow"` | The arrow. |
| `data-uncentered` | Present when it can’t point at the trigger’s center. |

---

# Tree

> Nested, expandable rows for files and hierarchies, with indent guides, connector lines, cascading checkboxes, typeahead and full keyboard support.

Docs: https://hextaui.com/docs/tree
Markdown: https://hextaui.com/docs/tree.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/tree.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/tree.tsx`, `components/ui/checkbox.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  Tree,
  TreeGroup,
  TreeItem,
  TreeItemLabel,
} from "@/components/ui/tree"
```

```tsx
<Tree aria-label="Files" defaultExpandedValues={["src"]}>
  <TreeItem value="src">
    <TreeItemLabel icon={<IconFolder />}>src</TreeItemLabel>
    <TreeGroup>
      <TreeItem value="index">
        <TreeItemLabel icon={<IconFile />}>index.ts</TreeItemLabel>
      </TreeItem>
    </TreeGroup>
  </TreeItem>
</Tree>
```

An item with a `<TreeGroup />` is a branch: it gets a chevron, opens and closes, and answers to the arrow keys. Every item needs a `value` that is unique within the tree.

## Composition

```text
Tree
└── TreeItem
    ├── TreeItemLabel
    └── TreeGroup
        └── TreeItem
            └── TreeItemLabel
```

## Examples

### Indent guides

`variant="lines"` draws a guide for each level. The guide of the branch that holds the selected or focused row gets darker, so you can see where you are in deep trees.

### Connectors

`variant="connectors"` joins each item to its parent with an elbow, like a terminal tree listing. Use `meta` for versions, sizes or counts.

### Checkboxes

With `checkboxes`, checking a branch checks every enabled item inside it, and a partly checked branch shows a dash. Checking a branch also counts as checking children you load later. Clicking a row checks it, and the chevron opens it.

### Navigation

Render rows as links with `render`. Pass the current page to `selectedValues`, open its section, and set `aria-current` on its row.

### Multiple selection

`selectionMode="multiple"` works like a file manager: click to select one row, Cmd/Ctrl+click to add or remove one, Shift+click to select a range. On touch screens a tap adds or removes the row.

### Controlled

Keep open branches in your own state with `expandedValues` and `onExpandedValuesChange`. This example also builds the tree from data with a recursive function.

### Lazy loading

Fetch children in `onExpandedChange` on `<TreeItem />`. Render a disabled loading row until they arrive, so the branch keeps its chevron.

### Small

`size="sm"` uses shorter rows and tighter indents, for sidebars. Rows grow on touch screens in both sizes.

### Disabled

A disabled item can’t be selected, checked or opened, and the arrow keys skip it. Items inside a disabled branch are disabled too.

### Long names

Names cut off with an ellipsis and `meta` stays visible. Pass `title` to show the full name on hover.

### Right to left

Indents, connectors and chevrons mirror, and the left and right arrow keys swap.

## Keyboard

| Key | Action |
| --- | --- |
| `↓` | Moves focus to the next visible row. |
| `↑` | Moves focus to the previous visible row. |
| `→` | Opens a closed branch. On an open branch, moves focus to its first child. |
| `←` | Closes an open branch. Otherwise moves focus to the parent. |
| `Home` | Moves focus to the first row. |
| `End` | Moves focus to the last visible row. |
| `Enter` | Selects the row and opens or closes it if it is a branch. Follows the link on link rows. |
| `Space` | Selects the row, adds or removes it in multiple mode, or checks it with checkboxes. |
| `Shift + ↑` `Shift + ↓` | Extends the selection in multiple mode. |
| `Cmd/Ctrl + A` | Selects every visible row in multiple mode. |
| `*` | Opens every branch at the focused row’s level. |
| `a–z` | Moves focus to the next row whose name starts with the typed letters. |

## Accessibility

The tree follows the WAI-ARIA tree view pattern. Each row is the `treeitem` and owns its group through `aria-owns`, so a row’s name is only its own label and link rows work as real links. Only one row is in the tab order at a time. When a branch closes around the focused row, focus moves to that branch instead of getting lost.

Closed groups stay in the page, so the browser’s find-in-page opens the folders around a match, and checking a branch sees every item inside it. Give the tree an `aria-label`.

## API reference

Branches open and close with the Base UI collapsible. `<TreeItem />` and `<TreeGroup />` accept the props of the parts they wrap.

### Tree

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "lines" \| "connectors"` | `"default"` |  |
| `size` | `"default" \| "sm"` | `"default"` |  |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"single"` |  |
| `selectedValues` | `string[]` | – |  |
| `defaultSelectedValues` | `string[]` | – |  |
| `onSelectedValuesChange` | `(values: string[]) => void` | – |  |
| `expandedValues` | `string[]` | – |  |
| `defaultExpandedValues` | `string[]` | – |  |
| `onExpandedValuesChange` | `(values: string[]) => void` | – |  |
| `checkboxes` | `boolean` | `false` | Show cascading checkboxes. Rows are checked instead of selected. |
| `checkedValues` | `string[]` | – | Checked items. A branch in the list counts as checking its children. |
| `defaultCheckedValues` | `string[]` | – |  |
| `onCheckedValuesChange` | `(values: string[]) => void` | – | Called with every checked leaf and every fully checked branch. |
| `disabled` | `boolean` | `false` |  |
| `hiddenUntilFound` | `boolean` | `true` | Let find-in-page open closed branches around a match. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="tree"` | Target the root in CSS. |
| `data-variant` | The current variant. |
| `data-size` | The current size. |
| `--tree-row-height` | Row height. Larger on touch screens. |
| `--tree-indent` | How far each level is indented. |

### TreeItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | Required. Unique within the tree. |
| `disabled` | `boolean` | `false` |  |
| `onExpandedChange` | `(expanded: boolean) => void` | – | Called when this item opens or closes. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="tree-item"` | Target items in CSS. |
| `data-open` | Present when the item is open. |
| `data-disabled` | Present when the item is disabled. |

### TreeItemLabel

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | – | Shown before the label. |
| `expandedIcon` | `ReactNode` | – | Crossfades in for icon while the branch is open. |
| `meta` | `ReactNode` | – | Shown at the end of the row, such as a size, count or status. |
| `className` | `string` | – |  |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<div>` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="tree-item-label"` | Target rows in CSS. |
| `data-value` | The item’s value. |
| `data-expanded` | Present when the branch is open. |
| `data-selected` | Present when the row is selected. |
| `data-checked` | Present when the row is checked. |
| `data-indeterminate` | Present when only some children are checked. |
| `data-disabled` | Present when the item is disabled. |

### TreeGroup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | – | Applied to the inner wrapper, so padding never fights the height animation. |

| Attribute | Description |
| --- | --- |
| `data-slot="tree-group"` | Target groups in CSS. |
| `data-open` | Present when the group is open. |
| `data-starting-style` | Present while the group animates in. |
| `data-ending-style` | Present while the group animates out. |
| `--collapsible-panel-height` | The group’s measured height, used for the height animation. |

---

# Video player

> A video player with a scrubbable seek bar, auto-hiding controls, keyboard shortcuts, speed, picture in picture and full screen.

Docs: https://hextaui.com/docs/video-player
Markdown: https://hextaui.com/docs/video-player.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/video-player.json
```

This adds the component, the HextaUI theme tokens and any HextaUI components it depends on.

### Manual

Add the HextaUI theme tokens (https://hextaui.com/docs/installation#theme) to your global CSS if you haven't yet, then install the dependencies.

```bash
pnpm add @base-ui/react @tabler/icons-react class-variance-authority cn
```

Copy `components/ui/video-player.tsx`, `components/ui/button.tsx`, `components/ui/dropdown-menu.tsx`, `components/ui/kbd.tsx`, `components/ui/spinner.tsx`, `components/ui/tooltip.tsx` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  VideoPlayer,
  VideoPlayerContent,
  VideoPlayerControls,
  VideoPlayerFullscreenButton,
  VideoPlayerPlayButton,
  VideoPlayerSeekBar,
  VideoPlayerSpacer,
  VideoPlayerTime,
  VideoPlayerVolume,
} from "@/components/ui/video-player"
```

```tsx
<VideoPlayer>
  <VideoPlayerContent src="/intro.mp4" poster="/intro.jpg" />
  <VideoPlayerControls>
    <VideoPlayerSeekBar />
    <VideoPlayerPlayButton />
    <VideoPlayerVolume />
    <VideoPlayerTime />
    <VideoPlayerSpacer />
    <VideoPlayerFullscreenButton />
  </VideoPlayerControls>
</VideoPlayer>
```

## Composition

```text
VideoPlayer
├── VideoPlayerContent
└── VideoPlayerControls
    ├── VideoPlayerPlayButton
    ├── VideoPlayerSeekButton
    ├── VideoPlayerSeekBar
    ├── VideoPlayerTime
    ├── VideoPlayerSpacer
    ├── VideoPlayerVolume
    ├── VideoPlayerPlaybackRate
    ├── VideoPlayerCaptionsButton
    ├── VideoPlayerPictureInPictureButton
    └── VideoPlayerFullscreenButton
```

## Examples

### Bar

`variant="bar"` puts the controls under the picture on the page surface. They never hide or cover the video.

### Minimal

Use only the parts you need. `tooltips={false}` turns off the hover hints, and `type="remaining"` counts down instead of up.

### Seek offsets and speeds

`offset` sets how far each seek button jumps, and `rates` sets the speeds in the menu.

### Page-wide shortcuts

Shortcuts work while focus is inside the player. `globalShortcuts` also listens on the page, but never while you type in a field, use a button or have a menu or dialog open. Use it for one player per page.

### Captions

Add a `<track>` and `VideoPlayerCaptionsButton`. Captions are drawn by the player, so they move up while the controls show instead of hiding behind them. A cross-origin track needs `crossOrigin` on the video.

### Custom controls

`useVideoPlayer` reads state and actions from any component inside the player. Select only what you use, so the component re-renders only when that value changes.

### Error

When the source fails, the player shows `errorMessage`, announces it and disables the controls that can’t work.

### Right to left

Labels follow the page language. The timeline and transport controls stay left to right, the way platform media players do.

## Keyboard

These work while focus is anywhere inside the player, or on the page with `globalShortcuts`. They are skipped while a modifier key is held or focus is in a text field.

| Key | Action |
| --- | --- |
| `Space` `K` | Plays or pauses. |
| `J` | Goes back 10 seconds. |
| `L` | Goes forward 10 seconds. |
| `←` `→` | Goes back or forward 5 seconds. On the seek bar, Shift jumps 10. |
| `↑` `↓` | Turns the volume up or down by 5%. |
| `M` | Mutes or unmutes. |
| `C` | Turns captions on or off, when the video has them. |
| `F` | Enters or leaves full screen. |
| `I` | Opens or closes picture in picture, where supported. |
| `Shift+.` `Shift+,` | Speeds up or slows down playback. |
| `0–9` | Jumps to 0% through 90% of the video. |
| `Home` `End` | Jumps to the start or the end. |

## Accessibility

- The player is a labelled region. Every button has a name that follows its state (Play, Pause, Replay) and a tooltip with its shortcut.
- The seek bar and volume are sliders. The seek bar reads its value as “1 minute 5 seconds of 3 minutes”.
- Actions from shortcuts and video clicks are announced politely, for example “Paused” or “Volume 40%”. Load errors are announced as an alert.
- In the overlay variant, controls fade out after 2.5 seconds of playback without pointer movement. They stay visible while paused, while you hover or use them with the keyboard, and while a menu is open.
- On touch screens, a tap shows or hides the controls and a double tap on the left or right third goes back or forward 10 seconds. Keep tapping to add 10 seconds each time.
- The captions button is a toggle with `aria-pressed`. It picks the last track you used, then one in the browser’s language, then the first one.
- With reduced motion, controls and feedback fade without moving or scaling.

## API reference

The seek bar and volume are built on the Base UI slider, and the buttons on HextaUI’s Button, Tooltip and Dropdown menu.

### VideoPlayer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"overlay" \| "bar"` | `"overlay"` | overlay floats auto-hiding controls over the video. bar puts them below it. |
| `shortcuts` | `boolean` | `true` | Keyboard shortcuts while focus is in the player. |
| `globalShortcuts` | `boolean` | `false` | Also listen for shortcuts on the whole page. |
| `errorMessage` | `ReactNode` | `"This video can’t be played."` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player"` | Target the root in CSS. |
| `data-variant` | The current variant. |
| `data-controls` | "visible" or "hidden". The cursor hides with the controls. |
| `data-fullscreen` | Present while the player is full screen. |
| `aria-busy` | Set while playback waits for data. |

### VideoPlayerContent

The `<video>` element. It takes every video attribute, and `<source>` or `<track>` children. A click plays or pauses, a double click toggles full screen, a tap shows or hides the controls and a double tap at either side seeks.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoPlay` | `boolean` | `false` | Starts playback on mount, except under reduced motion. |
| `playsInline` | `boolean` | `true` |  |
| `preload` | `"none" \| "metadata" \| "auto"` | `"metadata"` |  |
| `doubleTapSeek` | `number \| false` | `10` | Seconds a double tap at either side jumps on touch screens. false turns it off. |
| `render` | `ReactElement \| (props, state) => ReactElement` | `<video>` | Swap in another media element, such as an HLS video element. |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-content"` | Target the video in CSS. |

### VideoPlayerControls

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tooltips` | `boolean` | `true` | Show each control’s label and shortcut on hover. |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-controls"` | Target the control bar in CSS. |
| `data-hidden` | Present while overlay controls are hidden. |

### VideoPlayerSeekBar

Always takes its own row above the buttons. Hover shows the time under the pointer, and the lighter track shows what has loaded.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Seek"` |  |
| `onValueChange` | `(value: number, details) => void` | – |  |
| `onValueCommitted` | `(value: number, details) => void` | – |  |
| `disabled` | `boolean` | `false` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-seek-bar"` | Target the seek bar in CSS. |
| `data-dragging` | Present while you scrub. |
| `data-previewing` | Present on the control while the hover time is shown. |
| `--video-player-buffered` | The loaded part of the video, from 0 to 1. |
| `--video-player-hover` | The pointer position along the bar, from 0 to 1. |

### VideoPlayerPlayButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `playLabel` | `string` | `"Play"` |  |
| `pauseLabel` | `string` | `"Pause"` |  |
| `replayLabel` | `string` | `"Replay"` |  |
| `...props` | `ButtonProps` | – | Every Button prop, including variant and size. |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-play-button"` | Target the button in CSS. |
| `data-state` | "paused", "playing" or "ended". |

### VideoPlayerSeekButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `offset` | `number` | `10` | Seconds to jump. Negative values go back. |
| `label` | `string` | `"Forward 10 seconds"` |  |
| `...props` | `ButtonProps` | – | Every Button prop, including variant and size. |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-seek-button"` | Target the button in CSS. |
| `data-direction` | "backward" or "forward". |

### VideoPlayerVolume

A mute button with a slider that opens on hover or focus. On touch screens only the mute button shows, since phones control volume with their own buttons.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Volume"` |  |
| `muteLabel` | `string` | `"Mute"` |  |
| `unmuteLabel` | `string` | `"Unmute"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-volume"` | Target the group in CSS. |
| `data-slot="video-player-mute-button"` | The mute button. Also exported as VideoPlayerMuteButton. |
| `data-state` | On the mute button: "muted", "low" or "high". |

### VideoPlayerTime

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `"both" \| "elapsed" \| "remaining" \| "duration"` | `"both"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-time"` | Target the time in CSS. |
| `data-type` | The current type. |

### VideoPlayerPlaybackRate

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rates` | `number[]` | `[0.5, 0.75, 1, 1.25, 1.5, 2]` |  |
| `label` | `string` | `"Playback speed"` |  |
| `normalLabel` | `string` | `"Normal"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-playback-rate"` | Target the menu trigger in CSS. |

### VideoPlayerFullscreenButton

Makes the whole player full screen, or the video itself on iPhone. Renders nothing where full screen isn’t available.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enterLabel` | `string` | `"Full screen"` |  |
| `exitLabel` | `string` | `"Exit full screen"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-fullscreen-button"` | Target the button in CSS. |
| `data-state` | "on" or "off". |

### VideoPlayerCaptionsButton

Renders nothing until the video has a subtitles or captions track.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `"Captions"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-captions-button"` | Target the button in CSS. |
| `data-state` | "on" or "off". |
| `data-slot="video-player-captions"` | The caption text on the video. data-lifted is present while it sits above the controls. |

### VideoPlayerPictureInPictureButton

Renders nothing in browsers without picture in picture.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enterLabel` | `string` | `"Picture in picture"` |  |
| `exitLabel` | `string` | `"Exit picture in picture"` |  |

| Attribute | Description |
| --- | --- |
| `data-slot="video-player-pip-button"` | Target the button in CSS. |
| `data-state` | "on" or "off". |

### VideoPlayerSpacer

Fills the free space in the control row, pushing the controls after it to the end.

### useVideoPlayer

Returns the player’s state and actions. Pass a selector that returns a single value.

```tsx
const paused = useVideoPlayer((player) => player.paused)
const seek = useVideoPlayer((player) => player.seek)
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `paused, ended, started, waiting, scrubbing, currentTime, duration, buffered, volume, muted, playbackRate, fullscreen, pictureInPicture, error, hasCaptions, captions, caption` | – |  |
| `actions` | `play, pause, togglePaused, seek, seekBy, setVolume, toggleMuted, setPlaybackRate, toggleFullscreen, togglePictureInPicture, toggleCaptions` | – |  |

---

# useAutosize

> Grows a textarea with what you write between its minimum and maximum height, animating each change without ever touching the text.

Docs: https://hextaui.com/docs/use-autosize
Markdown: https://hextaui.com/docs/use-autosize.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-autosize.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-autosize.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useAutosize } from "@/hooks/use-autosize"
```

```tsx
const ref = React.useRef<HTMLTextAreaElement>(null)
useAutosize(ref, true, value)

<textarea
  ref={ref}
  rows={1}
  value={value}
  onChange={(event) => setValue(event.target.value)}
  className="min-h-[calc(1lh+1rem)] max-h-[calc(8lh+1rem)] resize-none"
/>
```

`<Textarea autoResize>` already uses this hook. Call it yourself when you render your own `<textarea>`, such as a chat composer or an inline editor.

## How it works

On each change the hook sets the height to `auto`, reads the natural `scrollHeight`, and clamps it to the element's own CSS `min-height` and `max-height`. All of that happens before paint, so you never see the collapsed frame. The bounds stay in your CSS, so they can be responsive or use `lh` to count lines.

```bash
min-h-[calc(2lh+1rem)]   at least two lines plus the vertical padding
max-h-[calc(8lh+1rem)]   then scroll after eight
max-h-64                 or any fixed length
```

- Height changes animate over 180ms, and a change that comes in mid-animation starts from the current height, so fast typing never jumps. Under reduced motion the height snaps.
- Past `max-height` the textarea scrolls. Otherwise its scrollbar stays hidden, so it doesn't flash on each new line.
- It refits when the width changes, because text that wraps differently changes the height.
- It listens for `input` on `window` and only measures. It never reads or writes the value, so keystrokes are never delayed or dropped.

## Examples

### Controlled values

Typing fires `input`, but setting `value` from code doesn't. Pass the value as the third argument and the textarea refits when you insert a template or clear it.

## Good to know

- Set `rows={1}` and `resize-none`. A manual resize handle fights the automatic height.
- Turning `enabled` off or unmounting removes the inline height and overflow, handing the size back to your CSS.
- On touch screens, use at least 16px text in the textarea, or iOS zooms in when it's focused.

## API reference

### useAutosize(ref, enabled, value)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ref` | `RefObject<HTMLTextAreaElement \| null>` | – | The textarea to size. |
| `enabled` | `boolean` | – | Whether to size automatically. |
| `value` | `unknown` | – | The controlled value. Pass undefined for uncontrolled textareas. |

### Used by

`Textarea` and `InputGroupTextarea`.

---

# useButtonFeedback

> Runs an async action through loading, success and error, skipping the spinner for fast requests and holding an error while you read it.

Docs: https://hextaui.com/docs/use-button-feedback
Markdown: https://hextaui.com/docs/use-button-feedback.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-button-feedback.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-button-feedback.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useButtonFeedback } from "@/hooks/use-button-feedback"
```

```tsx
const { buttonProps, track } = useButtonFeedback()

<form onSubmit={(event) => {
  event.preventDefault()
  track(() => saveProfile(new FormData(event.currentTarget)))
}}>
  …
  <Button type="submit" {...buttonProps}>Save</Button>
</form>
```

`<Button feedback>` runs this flow for you when its `onClick` returns a promise. Use the hook when the work starts somewhere else, like a form's `onSubmit`, a keyboard shortcut or a blur. It also works when the status belongs on something that isn't a button.

## How it works

`track()` takes a promise, or a function that returns one, and moves `status` through `idle`, `loading`, then `success` or `error`, and back to `idle`. The timing is what makes it feel calm.

| Step | Description |
| --- | --- |
| `0–150ms` | Status stays idle. A request that settles in this window goes straight to success or error, without a spinner. |
| `loading` | Shown from 150ms. Once shown it lasts at least 400ms, so it never flashes. |
| `success` | Held for 2 seconds by default, then returns to idle. |
| `error` | Held for 4 seconds by default. While the pointer is over the button, or it has keyboard focus, the reset waits until they leave, plus 600ms. |

- Calls to `track()` while a request is in flight are ignored, so a double click or a held Enter key never sends the request twice.
- A function passed to `track()` that throws synchronously is treated like a rejected promise.
- `reset()` returns to idle at once. Whatever the abandoned request does later is ignored, and so is anything that settles after the component unmounts.
- The error hold only counts a real mouse hover and keyboard focus. Touch has no hover, and a click's focus isn't `:focus-visible`, so neither one pins the error.

## Examples

### Forms

Call `track()` from `onSubmit` and spread `buttonProps` on the submit button. Remove the @ to see the error.

### Status without a button

Read `status` to drive any UI. This note saves when it loses focus and shows the result beside it, in a `role="status"` region that screen readers announce.

### Timing and errors

```tsx
const { status, error, track, reset } = useButtonFeedback({
  resetAfter: { success: 1500, error: 6000 },
  onError: (error) => reportError(error),
})
```

`resetAfter` takes one number for both outcomes, or an object to set each one. `error` holds the last rejection reason, so you can show it in the label, as [Button's error details](https://hextaui.com/docs/button#error-details) example does.

## Good to know

- Give each button its own hook. Two buttons sharing one `buttonProps` both show the same status.
- `onStatusChange` and `onError` always call the latest function you passed, so inline functions are fine.
- Use `isPending()` to guard work outside `track()`. It reads a ref, so it's accurate even before the next render.

## API reference

### useButtonFeedback(options?)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `resetAfter` | `number \| { success?: number; error?: number }` | `{ success: 2000, error: 4000 }` | How long success and error stay before returning to idle. |
| `onStatusChange` | `(status: ButtonStatus) => void` | – | Called on every status change. |
| `onError` | `(error: unknown) => void` | – | Called with the rejection reason. |

### Returns

| Property | Description |
| --- | --- |
| `track(action)` | Pass a promise or a function returning one. Ignored while a request is in flight. |
| `buttonProps` | status plus pointer and focus handlers. Spread on <Button>, or on anything that composes those handlers. |
| `status` | "idle" \| "loading" \| "success" \| "error" |
| `error` | The last rejection reason. |
| `reset()` | Returns to idle now and ignores the request in flight. |
| `isPending()` | Whether a request is in flight. |

### Used by

`Button` through its `feedback` prop.

---

# useComposedRef

> Keeps a ref to your own element while still forwarding it to whatever ref the parent passed in.

Docs: https://hextaui.com/docs/use-composed-ref
Markdown: https://hextaui.com/docs/use-composed-ref.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-composed-ref.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-composed-ref.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useComposedRef } from "@/hooks/use-composed-ref"
```

```tsx
function SearchInput({ ref, ...props }: React.ComponentProps<"input">) {
  const [inputRef, setRef] = useComposedRef<HTMLInputElement>(ref)

  React.useEffect(() => {
    inputRef.current?.select()
  }, [inputRef])

  return <input ref={setRef} {...props} />
}
```

In React 19, `ref` is a regular prop. When your component also needs the element for itself, you have two refs and only one `ref` attribute. This hook gives you an object ref to read, plus a callback that fills both refs.

## The problem it solves

```tsx
function SearchInput({ ref, ...props }: React.ComponentProps<"input">) {
  const inputRef = React.useRef<HTMLInputElement>(null)
  return <input ref={inputRef} {...props} />
}
```

This compiles, but the parent's `ref` is dropped, so `ref.current` stays `null` in the parent. With `useComposedRef`, both the parent and the component get the element.

- The returned `inputRef` is a normal `RefObject`, so you can pass it to hooks that expect one, like `useAutosize` or `useInvalidShake`.
- `setRef` keeps the same identity while the parent's ref does, so React doesn't detach and reattach it on every render.
- Works with object refs, callback refs and no ref at all.

## Composed or merged

Use `useComposedRef` when you combine exactly one forwarded ref with your own object ref, which is most components. Use [useMergedRef](https://hextaui.com/docs/use-merged-ref) when you combine more than two, when one of them is a callback ref from another hook, or when a forwarded callback ref returns a React 19 cleanup function. `useComposedRef` calls a callback ref with `null` on detach instead of running its cleanup.

## API reference

### useComposedRef(ref)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ref` | `Ref<T> \| undefined` | – | The ref your component received. |

| Returns | Description |
| --- | --- |
| `[0] RefObject<T \| null>` | Your own ref to the element. |
| `[1] (node: T \| null) => void` | Pass to the element's ref. Fills both refs. |

### Used by

`Input`, `Textarea`, `NativeSelect`, `Field` and `InputGroup`.

---

# useDelayedLoading

> Shows a loading state only when work is actually slow, then keeps it up long enough that it never flickers.

Docs: https://hextaui.com/docs/use-delayed-loading
Markdown: https://hextaui.com/docs/use-delayed-loading.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-delayed-loading.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-delayed-loading.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useDelayedLoading } from "@/hooks/use-delayed-loading"
```

```tsx
const { data, isFetching } = useQuery(query)
const showSpinner = useDelayedLoading(isFetching)

return showSpinner ? <Spinner /> : <Results data={data} />
```

Pass the raw loading flag and render from the boolean it returns. Most requests on a warm connection finish in under 150ms. Showing a spinner for those is worse than showing nothing: it flashes for a frame or two and reads as a glitch, not as progress.

## How it works

The hook applies two rules. It waits for `delay` before showing anything, so work that finishes sooner never shows a loading state. Once the indicator is visible, it stays for at least `minDuration`, so it can't appear and vanish within a few frames.

| Work takes | Description |
| --- | --- |
| `80ms` | Nothing is shown. |
| `250ms` | Shown at 150ms and held until 550ms, the 400ms minimum. |
| `900ms` | Shown at 150ms and hidden as soon as work ends. |

The 400ms minimum is long enough to register as a deliberate state and short enough not to slow anyone down.

- If `loading` turns back on while the indicator is still visible, it simply stays visible. There's no hide and show again.
- Timers are cleared when the inputs change or the component unmounts, so nothing updates state after it's gone.
- On the server and during the first render it returns `false`, so it never adds a hydration mismatch.

## Examples

### Skeletons

Skeletons replace content, so a flash is even more jarring than with a spinner. Here the first load is slow and shows the skeleton. Later loads come from a cache and never do.

### Tuning the timing

```tsx
const showSkeleton = useDelayedLoading(isLoading, {
  delay: 300,
  minDuration: 600,
})
```

Raise `delay` for indicators that cover a lot of the screen, like skeletons or overlays. Lower it toward 0 for actions where any wait needs acknowledging, like a payment. Keep `minDuration` above roughly 300ms.

## Good to know

- `<Spinner loading={...} />` and `<Button loading>` already use these timings. Reach for the hook when you render something else.
- Keep the space the indicator will take, as the examples do, so the layout doesn't shift when it appears.
- Pair it with an `aria-busy` or a status message. The hook only decides what to show visually.

## API reference

### useDelayedLoading(loading, options?)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` | `boolean` | – | Whether the work is in progress right now. |
| `options.delay` | `number` | `150` | Milliseconds to wait before showing the loading state. |
| `options.minDuration` | `number` | `400` | Minimum milliseconds the loading state stays visible once shown. |

| Returns | Description |
| --- | --- |
| `boolean` | Whether to show the loading state. Always false on the server. |

### Used by

`Spinner` through its `loading` prop.

---

# useHeldKeys

> The keys someone is holding down right now, shared by every subscriber through a single set of window listeners.

Docs: https://hextaui.com/docs/use-held-keys
Markdown: https://hextaui.com/docs/use-held-keys.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-held-keys.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-held-keys.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useHeldKeys } from "@/hooks/use-held-keys"
```

```tsx
const held = useHeldKeys(true)
const showShortcutHints = held.has("meta") || held.has("ctrl")
```

Use it for anything that reacts to keys being held rather than pressed: keycaps that press down, shortcut hints that appear while you hold ⌘, or a modifier that switches a tool, like Alt to duplicate while dragging.

## How it works

Every component that calls the hook shares one store. The first subscriber adds passive `keydown` and `keyup` listeners to `window`, and the last one to unsubscribe removes them. A page with fifty listening keycaps still has one pair of listeners.

The listeners only read events. They never call `preventDefault`, and they sit on `window`, after React's own handlers, so typing in a field is never delayed or changed.

```bash
"meta" "ctrl" "alt" "shift"     modifiers, left and right alike
"a" … "z"  "0" … "9"            letters and digits, by physical key
"space" "enter" "escape" "tab"   named keys, lowercased
"arrowup" "arrowdown" "f1" …
```

- Letters and digits come from `event.code`, the physical key, so holding Option+K on a Mac still reports `k` rather than `˚`.
- Key repeat is ignored, and nothing re-renders while a key is held.
- macOS doesn't send `keyup` for other keys while ⌘ is down. When ⌘ is released, the store keeps only the modifiers still held, so letters can't get stuck.
- Everything is released when the window loses focus or the tab is hidden. A shortcut that switches apps leaves nothing held.

## Examples

### Keycaps that press

`<Kbd listen>` is built on this hook. Each keycap presses down while its key is held.

## Good to know

- Pass `false` to stop listening. The hook then returns an empty set and adds no listeners, so it's cheap to call it unconditionally.
- The set is replaced only when a key goes down or up, so its identity works as a memo or effect dependency.
- For shortcuts that fire an action, use `matchesHotkey` from `Hotkey` in a keydown handler instead. Holding keys is for showing state, not for running commands.
- On the server, and before hydration, the set is empty.

## API reference

### useHeldKeys(enabled)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | `boolean` | – | Whether to listen. When false, nothing is attached. |

| Returns | Description |
| --- | --- |
| `ReadonlySet<string>` | The names of the keys held down right now. |

### Used by

`Kbd` and `KbdGroup` through their `listen` prop.

---

# useInvalidShake

> Shakes a form control when a submit attempt finds it invalid, and never while someone is still typing.

Docs: https://hextaui.com/docs/use-invalid-shake
Markdown: https://hextaui.com/docs/use-invalid-shake.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-invalid-shake.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-invalid-shake.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useInvalidShake } from "@/hooks/use-invalid-shake"
```

```tsx
const ref = React.useRef<HTMLSelectElement>(null)
useInvalidShake(ref)

<form>
  <select
    ref={ref}
    required
    className="data-shake:motion-safe:animate-button-shake"
  >
    …
  </select>
  <button type="submit">Continue</button>
</form>
```

The hook only sets a `data-shake` attribute. The motion comes from the theme's `animate-button-shake`, which you attach with `data-shake:motion-safe:animate-button-shake`. HextaUI's Input, Textarea, Native select and Input group already include that class and call the hook. Use it directly for your own controls.

## When it shakes

A shake answers one question: why didn't my submit work? So the hook only shakes right after someone tries to submit, and never while they're still filling in the form.

| Event | Description |
| --- | --- |
| `Submit attempt` | Clicking a submit button, pressing Enter in an input of the form, or the form's submit event. |
| `Invalid within 600ms` | The control fires invalid, or has aria-invalid="true", data-invalid or :user-invalid. That covers native validation, Base UI fields and server errors set right after submitting. |
| `Shake` | data-shake is set for 400ms. It shakes once per attempt, however many of those signals arrive. |

- Inside an `InputGroup`, the whole group shakes, not just the inner control.
- Under reduced motion, nothing is set. Pair the shake with a visible error message either way, since the shake is a cue, not the message.
- The hook needs the control to belong to a `<form>`. Without one, it does nothing.

## Good to know

- Turn it off per control with the `enabled` argument, or with `shake={false}` on HextaUI's inputs.
- Restarting the attribute restarts the animation, so a second failed attempt shakes again even if the first is still running.
- Native validation focuses the first invalid control on submit. The shake only adds motion on top of that and never moves focus.

## API reference

### useInvalidShake(ref, enabled?)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ref` | `RefObject<HTMLInputElement \| HTMLTextAreaElement \| HTMLSelectElement \| null>` | – | The form control to watch. |
| `enabled` | `boolean` | `true` | Whether to shake. |

| Attribute | Description |
| --- | --- |
| `data-shake` | Present for 400ms after a failed submit attempt, on the control or its InputGroup. |

### Used by

`Input`, `Textarea`, `NativeSelect` and `InputGroup`.

---

# useMergedRef

> Combines any number of callback and object refs into one, with React 19 ref cleanup for each of them.

Docs: https://hextaui.com/docs/use-merged-ref
Markdown: https://hextaui.com/docs/use-merged-ref.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-merged-ref.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-merged-ref.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useMergedRef } from "@/hooks/use-merged-ref"
```

```tsx
function Panel({ ref, ...props }: React.ComponentProps<"div">) {
  const localRef = React.useRef<HTMLDivElement>(null)
  const morphRef = useSizeMorph<HTMLDivElement>({ axis: "height" })
  const setRef = useMergedRef(ref, localRef, morphRef)

  return <div ref={setRef} {...props} />
}
```

An element has one `ref`, but components often need to hand it to several places: the parent that forwarded a ref, a local ref for effects, and hooks that work through a callback ref.`useMergedRef` returns one callback that feeds all of them.

## How it works

When the element attaches, every ref receives it. Object refs get `.current` set, and callback refs are called with the node. The merged callback returns a cleanup in the React 19 style. On detach it runs each callback ref's own cleanup, or calls the ref with `null` if it didn't return one, and resets object refs to `null`.

```tsx
const observeRef = React.useCallback((node: HTMLDivElement | null) => {
  if (!node) return
  const observer = new ResizeObserver(onResize)
  observer.observe(node)
  return () => observer.disconnect()
}, [onResize])

const setRef = useMergedRef(ref, observeRef)
```

That makes callback refs a good home for anything tied to the element's lifetime, like observers and listeners. Setup and teardown live together, and merging them with other refs keeps them working.

## Good to know

```tsx
useMergedRef(ref, (node) => console.log(node))

const logRef = React.useCallback((node) => console.log(node), [])
useMergedRef(ref, logRef)
```

- The merged callback changes whenever any ref changes. An inline arrow is a new ref on every render, so React detaches and reattaches the element each time. Wrap callback refs in `useCallback`.
- `undefined` and `null` refs are skipped, so you can pass optional props straight in.
- For one forwarded ref plus a local object ref, [useComposedRef](https://hextaui.com/docs/use-composed-ref) is shorter.

## API reference

### useMergedRef(...refs)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `...refs` | `Array<Ref<T> \| undefined>` | – | Object refs, callback refs or undefined. |

| Returns | Description |
| --- | --- |
| `(node: T \| null) => () => void` | Pass to the element's ref. Returns the combined cleanup. |

### Used by

`Field` and `InputGroup`.

---

# usePagination

> Turns a page and a page count into the list of pages and ellipses to render, keeping its length steady as the page moves.

Docs: https://hextaui.com/docs/use-pagination
Markdown: https://hextaui.com/docs/use-pagination.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-pagination.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-pagination.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { usePagination } from "@/hooks/use-pagination"
```

```tsx
const { items, page, hasPrevious, hasNext } = usePagination({
  page: currentPage,
  count: totalPages,
})

items.map((item) =>
  item.type === "ellipsis" ? (
    <span key={item.position}>…</span>
  ) : (
    <a key={item.page} href={`?page=${item.page}`}>{item.page}</a>
  )
)
```

The hook only does the math. It returns the list of pages and ellipses to render and leaves the markup to you, which is how `Pagination` builds its links. Use it to build your own pager, like dots for a carousel or a page picker in a table footer.

## How it works

The list always shows the first and last `boundaries` pages, and `siblings` pages on each side of the current one. An ellipsis fills any gap of two pages or more. A gap of exactly one page shows that page instead, because an ellipsis there would hide no more than it takes up.

```bash
count: 20, siblings: 1, boundaries: 1

page 1    1  2  3  4  5  …  20
page 6    1  …  5  6  7  …  20
page 20   1  …  16 17 18 19 20
```

Once there are enough pages, the list always has `2 × boundaries + 2 × siblings + 3` items. Near the ends, the window widens instead of shrinking. Because the length never changes, the pager keeps its width, and the next and previous buttons stay under the pointer as you click through.

- `count` and `page` are clamped: a page past the end becomes the last page, and anything that isn't a finite number falls back to the default.
- A `count` of 0 returns no items and a `page` of 0, so an empty table can render nothing without a special case.
- `siblings` and `boundaries` go from 0 to 10.
- Ellipses have a stable `position` of `start` or `end`. Use it as the React key.

## Examples

### Dots

With `boundaries: 0` the list is just a window around the current page. Ellipses become small dots, so a long set of slides never needs more than five targets.

## Good to know

- Mark the current page with `aria-current="page"` and wrap the list in a `<nav>` with a label.
- Hide ellipses from screen readers with `aria-hidden`. They carry no information that the page numbers don't.
- Show page numbers with `tabular-nums` so the buttons don't change width as the digits change.

## API reference

### usePagination(options)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | – | Total number of pages. |
| `page` | `number` | `1` | The current page, starting at 1. |
| `siblings` | `number` | `1` | Pages to show on each side of the current page. |
| `boundaries` | `number` | `1` | Pages to always show at the start and the end. |

### Returns

| Property | Description |
| --- | --- |
| `items` | PaginationItemData[] to render, in order. |
| `page` | The clamped current page. |
| `count` | The clamped page count. |
| `hasPrevious` | Whether there's a page before this one. |
| `hasNext` | Whether there's a page after this one. |

```tsx
type PaginationItemData =
  | { type: "page"; page: number }
  | { type: "ellipsis"; position: "start" | "end" }
```

### Used by

`Pagination`.

---

# useToday

> Today's date that rolls over at midnight and when the tab comes back, without a hydration mismatch.

Docs: https://hextaui.com/docs/use-today
Markdown: https://hextaui.com/docs/use-today.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/use-today.json
```

This adds the hook and anything it depends on.

### Manual

Copy `hooks/use-today.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import { useToday } from "@/hooks/use-today"
```

```tsx
const today = useToday()

if (!today) {
  return <Skeleton className="h-5 w-40" />
}

return <p>{format(today, "PPPP")}</p>
```

Reach for it whenever a component depends on the current date, such as highlighting today, disabling past days or counting down to a deadline.

## Why not new Date()

```tsx
const today = new Date()
```

Reading the date while rendering breaks in two ways:

- **Hydration mismatches.** The server renders in its time zone, possibly hours earlier. Near midnight, server and browser disagree on the day, and React throws away the server HTML.
- **Stale dates.** A tab left open overnight keeps showing yesterday as today until something else re-renders it.

`useToday` returns `undefined` on the server and during hydration, then the local date. It also re-renders at midnight and when the tab becomes visible again, because timers in background tabs can be paused and miss midnight.

## Examples

### Date bounds

Disable past days and anything more than 30 days out. Until today is known, nothing is disabled, so the server HTML matches the first client render.

### Date keys

```tsx
import {
  fromDateKey,
  getTodayKey,
  subscribeToday,
  toDateKey,
} from "@/hooks/use-today"

toDateKey(new Date(2026, 9, 5))
fromDateKey("2026-10-05")

const unsubscribe = subscribeToday(() => refreshAgenda())
```

The file also exports the pieces the hook is built from. Date keys are local `YYYY-MM-DD` strings. They compare by day, sort correctly and are safe to use as React keys or cache keys. `subscribeToday` calls you back at midnight and on tab return, outside React.

## Good to know

- The returned `Date` is midnight in local time, so comparing it with `<` or `>` compares days, not times.
- The same `Date` object comes back until the day changes, so it's safe to use in effect dependencies.
- Plan for the `undefined` render. A skeleton, or rendering without date-based limits, both work.

## API reference

### useToday()

| Returns | Description |
| --- | --- |
| `Date \| undefined` | Local midnight today. undefined on the server and while hydrating. |

### Helpers

| Export | Description |
| --- | --- |
| `toDateKey(date)` | A Date as a local YYYY-MM-DD string. |
| `fromDateKey(key)` | A YYYY-MM-DD string as a local-midnight Date. |
| `getTodayKey()` | Today's date key. |
| `subscribeToday(callback)` | Calls back at midnight and when the tab becomes visible. Returns an unsubscribe function. |

### Used by

`Calendar`, and `Date picker` through it.

---

# Hairline

> Borders and rings exactly one device pixel wide on every screen, through one variable the whole theme reads.

Docs: https://hextaui.com/docs/hairline
Markdown: https://hextaui.com/docs/hairline.md

## Installation

Hairline is part of the HextaUI theme. If you've added the theme or any component, you have it.

```bash
npx shadcn@latest add https://hextaui.com/r/theme.json
```

Or add it to your global CSS by hand.

```css title="app/globals.css"
@theme inline {
  --default-border-width: var(--hairline);
}

@utility border-hairline {
  border-width: var(--hairline);
}

:root {
  --hairline: 1px;

  @media (min-resolution: 1.5dppx) {
    --hairline: calc(1px / 1.5);
  }

  @media (min-resolution: 2dppx) {
    --hairline: 0.5px;
  }

  @media (min-resolution: 3dppx) {
    --hairline: calc(1px / 3);
  }

  @media (min-resolution: 4dppx) {
    --hairline: 0.25px;
  }
}
```

## Usage

```tsx
<div className="border" />
<ul className="divide-y" />
<div className="border-2 sm:border-hairline" />
<button className="inset-ring-(length:--hairline) inset-ring-border" />
<hr className="h-(--hairline) border-0 bg-border" />
```

You rarely need to reach for it. The theme makes it the default border width, so `border`, `border-t` and `divide-y` all draw hairlines. Use the variable directly where Tailwind has no default, like rings, outlines and lines drawn with a background.

## Why hairlines

A CSS pixel covers two or three physical pixels on most screens, so a `1px` border is really two or three device pixels thick. `--hairline` divides by the display's pixel ratio so every line is exactly one device pixel, the way native apps draw separators. On a standard display it stays 1px.

| Pixel ratio | Description |
| --- | --- |
| `1×` | 1px |
| `1.5×` | 0.667px |
| `2×` | 0.5px |
| `3×` | 0.333px |
| `4×` | 0.25px |

## Examples

### Lists and cards

Plain `border` and `divide-y`. Thinner separators group rows without boxing them in.

## Good to know

- HextaUI components draw edges with `inset-ring-(length:--hairline)` rather than borders. An inset ring takes no layout space, so a state that changes the ring's color or width never shifts the content.
- Hairlines are lighter on the page, so a border color tuned for 1px lines may look faint. The theme's `--border` is tuned for hairlines.
- Use `border-2` or wider for emphasis, like a selected card. Those stay in CSS pixels.

## API reference

| Name | Description |
| --- | --- |
| `--hairline` | One device pixel, in CSS pixels. |
| `border-hairline` | Sets border-width to --hairline. |
| `--default-border-width` | Set to --hairline, so border and divide default to it. |

---

# Hotkey

> Parse, label, announce and match keyboard shortcuts, with ⌘ on Apple platforms and Ctrl everywhere else.

Docs: https://hextaui.com/docs/hotkey
Markdown: https://hextaui.com/docs/hotkey.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/hotkey.json
```

This adds the utility and anything it depends on.

### Manual

Copy `lib/hotkey.ts` into your project. Their source is in this page's Markdown.

## Usage

```tsx
import {
  formatHotkey,
  matchesHotkey,
  parseHotkey,
  useIsApple,
} from "@/lib/hotkey"
```

```tsx
function SaveShortcut({ onSave }: { onSave: () => void }) {
  const apple = useIsApple()

  React.useEffect(() => {
    const onKeyDown = (event: KeyboardEvent) => {
      if (matchesHotkey(event, "mod+s")) {
        event.preventDefault()
        onSave()
      }
    }
    window.addEventListener("keydown", onKeyDown)
    return () => window.removeEventListener("keydown", onKeyDown)
  }, [onSave])

  return <span>Save {formatHotkey("mod+s", apple)}</span>
}
```

Write each shortcut once, as a string, and use the same string to display it, announce it and match it. `mod` means ⌘ on Apple platforms and Ctrl everywhere else. That's almost always what you want, since Ctrl+K on a Mac and ⌘K on Windows both feel wrong.

## Syntax

```bash
"mod+k"            ⌘K on Apple platforms, Ctrl+K elsewhere
"shift+mod+p"      modifiers in any order
"cmd+option+esc"   aliases: cmd, command, option, opt, control, esc, return
"alt+up"           up, down, left and right for the arrow keys
"mod++"            a literal plus key
"g g"              a sequence of two chords, separated by a space
```

Keys are separated by `+` and are case-insensitive. Named keys use the lowercase `KeyboardEvent.key` value, like `enter`, `tab`, `pageup` or `f5`. Use `space` for the space bar.

## Parsing

```tsx
parseHotkey("mod+shift+k")  // [["shift", "mod", "k"]]
parseHotkey("cmd+opt+esc")  // [["alt", "meta", "escape"]]
parseHotkey("g i")          // [["g"], ["i"]]
```

`parseHotkey` returns one array per chord, with aliases resolved and modifiers sorted into Apple's order: Control, Option, Shift, Command. Every label built from it reads in the order people expect to see it.

## Labels

```tsx
formatHotkey("mod+shift+k", true)   // "⇧⌘K"
formatHotkey("mod+shift+k", false)  // "Shift+Ctrl+K"
keyLabel("enter", true)             // "↵"
spokenKey("mod", true)              // "Command"
spokenKey("mod", false)             // "Control"
```

Apple platforms use symbols with no separator, the way menus show them. Windows and Linux use words joined by `+`. Symbols are hard to read aloud, so `spokenKey` gives the name a screen reader should announce instead. `<Kbd keys>` shows the symbol and puts the spoken name in visually hidden text.

`useIsApple()` picks the platform. It returns `true` on the server and during hydration, then the real answer, so a Windows visitor briefly sees ⌘ before Ctrl instead of getting a hydration error.

## Matching

### Shortcut listener

`matchesHotkey` checks a keydown event against a hotkey. Modifiers must match exactly, so `mod+b` doesn't fire for `mod+shift+b`.

- Letters and digits also match by physical key, so `alt+k` works on a Mac, where Option+K types `˚`.
- Shifted letters match: `shift+k` matches the `K` that Shift produces.
- It matches one chord. For sequences like `g i`, track the previous chord yourself.
- Skip shortcuts without modifiers while the focus is in a text field, so typing a letter never triggers a command.

## API reference

| Export | Description |
| --- | --- |
| `parseHotkey(hotkey)` | string[][]: one array per chord, with aliases resolved and modifiers sorted. |
| `formatHotkey(hotkey, apple)` | The label for one chord, such as ⇧⌘K or Shift+Ctrl+K. |
| `keyLabel(key, apple)` | The visible label for one key name. |
| `spokenKey(key, apple)` | The name a screen reader should announce for one key. |
| `matchesHotkey(event, hotkey)` | Whether a KeyboardEvent matches one chord, with exact modifiers. |
| `isApplePlatform()` | Reads navigator.platform. true on the server. |
| `useIsApple()` | isApplePlatform as a hydration-safe hook. |

### Used by

`Kbd` and `Command`.

---

# Motion

> The easing curves, durations and reduced-motion check every component animates with, plus hooks for size morphs and sliding highlights.

Docs: https://hextaui.com/docs/motion
Markdown: https://hextaui.com/docs/motion.md

## Installation

### CLI

```bash
npx shadcn@latest add https://hextaui.com/r/motion.json
```

This adds the utility and anything it depends on.

### Manual

Copy `lib/motion.ts` into your project. Their source is in this page's Markdown.

## Principles

Every HextaUI component moves with the same few curves and durations, so the library feels like one thing.

- **Ease out for things that respond to you.** Elements entering, expanding or following a click start fast and settle, so the interface feels immediate.
- **Short and interruptible.** Most motion is 150 to 300ms. Anything that can be reversed starts from where it is now rather than restarting.
- **Reduced motion is a second design, not an off switch.** Movement turns into instant changes or plain fades, and state stays readable.

## Easing

The theme defines the curves as Tailwind easing utilities, and `lib/motion` exports the same values for the Web Animations API.

| Class | Description |
| --- | --- |
| `ease-out-quint` | easeOut in JS. The default for movement: popovers, highlights, size changes. |
| `ease-out-cubic` | A softer ease out for color and shadow changes on hover and focus. |
| `ease-in-out-quart` | easeInOut in JS. For movement between two resting states that nobody triggered directly. |
| `ease-spring` | easeSpring in JS. A spring with a small overshoot, written as linear(), for things that land, like a toggle's thumb. |
| `ease-drawer` | The iOS sheet curve for drawers and sheets that slide in from an edge. |

```tsx
<div className="transition-transform duration-300 ease-out-quint motion-reduce:transition-none" />
<div className="transition-colors duration-150 ease-out-cubic" />
<aside className="transition-transform duration-500 ease-drawer" />
```

## Durations

```tsx
import { duration, easeOut, prefersReducedMotion } from "@/lib/motion"

element.animate(
  [{ opacity: 0, translate: "0 4px" }, { opacity: 1, translate: "0 0" }],
  {
    duration: prefersReducedMotion() ? 0 : duration.enter,
    easing: easeOut,
  }
)
```

| duration. | Description |
| --- | --- |
| `press: 100` | Pressed state going down. |
| `release: 200` | Coming back up after a press. |
| `hover: 150` | Hover and focus feedback. |
| `enter: 200` | Elements appearing. |
| `exit: 150` | Elements leaving. Exits are faster than entrances, so they never hold anything up. |
| `morph: 300` | Size and position changes. |

`prefersReducedMotion()` reads the media query at call time. Check it when an animation starts rather than once on mount, so changing the system setting applies right away. It returns `true` on the server.

## Size morphs

```tsx
const morphRef = useSizeMorph<HTMLButtonElement>({ axis: "width" })

<button ref={morphRef} className="overflow-hidden whitespace-nowrap">
  {copied ? "Copied to clipboard" : "Copy"}
</button>
```

- Any DOM change inside the element triggers a morph, whether text, children or icons. Size changes from outside, like a resize, don't, so the element follows its container without lag.
- A change mid-morph continues from the current size. While it runs, the element has `data-morphing`, which you can use to clip overflow or pause other transitions.
- Keep the element at its natural size: no fixed width or height on the animated axis. Add `overflow-hidden` so the new content doesn't spill out while it grows.
- It returns a callback ref. Combine it with other refs using `useMergedRef`.

## Sliding highlights

```tsx
const barRef = React.useRef<HTMLDivElement>(null)
const highlightRef = React.useRef<HTMLSpanElement>(null)
useSlidingHighlight(barRef, highlightRef, "[data-active]", "data-active")

<div ref={barRef} className="relative isolate flex">
  <span
    ref={highlightRef}
    aria-hidden="true"
    className="absolute top-0 -z-1 opacity-0 transition-all duration-300 ease-out-quint data-instant:transition-opacity data-visible:opacity-100"
  />
  {items}
</div>
```

- The highlight is sized and translated with inline styles. Give it `absolute top-0` and a transition on `transform`, `width`, `height` and `opacity`.
- The hook watches the attribute you name with a `MutationObserver`, so it follows state from anywhere, including Base UI's own `data-pressed`, `data-checked` or `aria-current`.
- `data-visible` is set while something matches. `data-instant` is set when the highlight should jump: on first appearance, on resize and scroll, and under reduced motion. Style it as `data-instant:transition-opacity`.
- It measures with the bar's scale in mind, so it stays aligned inside a dialog that's still zooming in.

## API reference

### useSizeMorph(options)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `axis` | `"width" \| "height"` | – | Which dimension to animate. |
| `enabled` | `boolean` | `true` | Whether to animate. |
| `duration` | `number` | `300` | Milliseconds. |
| `easing` | `string` | `easeOut` | Any CSS easing. |

### useSlidingHighlight(barRef, highlightRef, selector, attribute?)

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `barRef` | `RefObject<HTMLElement \| null>` | – | The positioned container. |
| `highlightRef` | `RefObject<HTMLElement \| null>` | – | The element to move. |
| `selector` | `string` | – | Matches the child to highlight. |
| `attribute` | `string` | `"data-popup-open"` | The attribute whose changes move the highlight. |

### Constants

| Export | Description |
| --- | --- |
| `easeOut` | cubic-bezier(0.23, 1, 0.32, 1) |
| `easeInOut` | cubic-bezier(0.77, 0, 0.175, 1) |
| `easeSpring` | A linear() spring. |
| `duration` | press, release, hover, enter, exit and morph. |
| `prefersReducedMotion()` | Whether reduced motion is on. true on the server. |

---

# Scroll fade

> Edges of a scroll area that fade only when there's more to see, driven by the scroll position in CSS alone.

Docs: https://hextaui.com/docs/scroll-fade
Markdown: https://hextaui.com/docs/scroll-fade.md

## Installation

Scroll fade is a set of Tailwind utilities from shadcn's `tailwind.css`. The HextaUI theme already imports it, so if you've added the theme or any component, you have it.

```bash
npx shadcn@latest add https://hextaui.com/r/theme.json
```

Without the theme, install `shadcn` and import its CSS after Tailwind.

```bash
pnpm add shadcn
```

```css title="app/globals.css"
@import "tailwindcss";
@import "shadcn/tailwind.css";
```

## Usage

```tsx
<div className="scroll-fade h-64 overflow-y-auto">…</div>
<div className="flex scroll-fade-x overflow-x-auto">…</div>
```

Add it to any element that scrolls. An edge fades only while there is more content past it, so a cut-off row signals "keep scrolling" and a list at rest keeps crisp edges.

## How it works

The fade is a `mask-image`, so content dissolves into whatever is behind it. There's no overlay gradient to match to the background, and it works on images, tinted surfaces and glass. A CSS scroll-driven animation grows each edge's fade over the first and last 96px of scrolling. No JavaScript runs, and it never re-renders.

- Each fade is 12% of the container, capped at 40px.
- Browsers without scroll-driven animations show both fades all the time. It's a little less precise, but still reads as scrollable.
- `scroll-fade-x`, `scroll-fade-s` and `scroll-fade-e` follow the writing direction, so the start fade sits on the right in right-to-left layouts.

## Examples

### Horizontal

A row of filters that scrolls sideways. Pair it with `no-scrollbar`, also from shadcn's CSS, when the fade alone shows that there's more.

### One edge

A chat starts at the bottom, so only older messages above need a hint. `scroll-fade-t` fades the top alone, and `scroll-fade-t-16` makes it taller.

### Size and reveal distance

```tsx
<div className="scroll-fade scroll-fade-16 overflow-y-auto">…</div>
<div className="scroll-fade scroll-fade-[20%] overflow-y-auto">…</div>
<div className="scroll-fade [--scroll-fade-reveal:12rem] overflow-y-auto">…</div>
```

Sizes take the spacing scale or any length or percentage. `--scroll-fade-reveal` sets how far you scroll before an edge reaches its full fade.

## Good to know

- The mask fades the element's own background and border too. Put the surface on a wrapper and the fade on the scrolling child, as the examples do.
- A mask hides everything near the edge, including focus rings. Give the scrolling element some padding so focused items aren't faded out.
- Use [Scroll area](https://hextaui.com/docs/scroll-area) instead when you also want custom scrollbars. It has its own fades, measured with JavaScript, which work in every browser.

## API reference

| Class | Description |
| --- | --- |
| `scroll-fade, scroll-fade-y` | Fades the top and bottom edges. |
| `scroll-fade-x` | Fades the start and end edges, following direction. |
| `scroll-fade-t, scroll-fade-b` | Fades only the top or bottom edge. |
| `scroll-fade-s, scroll-fade-e` | Fades only the start or end edge. |
| `scroll-fade-l, scroll-fade-r` | Fades only the left or right edge, ignoring direction. |
| `scroll-fade-<size>` | Size of every fade. |
| `scroll-fade-{t,b,s,e}-<size>` | Size of one edge's fade. |
| `scroll-fade-none` | Turns the fade off, for example at a breakpoint. |
| `--scroll-fade-reveal` | Scroll distance over which an edge fades in. Defaults to 96px. |

---

# Shimmer

> A band of light that sweeps across text for in-progress states, tinted from the text color and still under reduced motion.

Docs: https://hextaui.com/docs/shimmer
Markdown: https://hextaui.com/docs/shimmer.md

## Installation

Shimmer is a Tailwind utility from shadcn's `tailwind.css`. The HextaUI theme already imports it, so if you've added the theme or any component, you have it.

```bash
npx shadcn@latest add https://hextaui.com/r/theme.json
```

Without the theme, install `shadcn` and import its CSS after Tailwind.

```bash
pnpm add shadcn
```

```css title="app/globals.css"
@import "tailwindcss";
@import "shadcn/tailwind.css";
```

## Usage

```tsx
<p className="shimmer text-muted-foreground">Generating response…</p>
```

Use it on short text that describes work in progress, like an assistant thinking, a file processing or a step that's running. The moving highlight says "still working" without a spinner taking up space beside the words.

## How it works

The text is painted with a gradient through `background-clip: text`, and a lighter band slides across it. The band is derived from the text's own color, so it suits muted, foreground or colored text without configuration, and it brightens in dark mode, where a lighter band reads better.

- Under reduced motion the gradient is removed entirely and the text renders in its normal color.
- In right-to-left layouts the sweep reverses, so it still travels in reading direction.
- The text stays real text: selectable, searchable and read normally by screen readers.

## Examples

### Options

Speed, band width, color and angle are each one class.

### Status updates

Shimmer while a task runs, then sweep once with `shimmer-once` when it finishes. Changing the key restarts the sweep for each new step.

### Direction and breakpoints

```tsx
<p className="shimmer md:shimmer-none">Generating response…</p>
<p className="shimmer shimmer-reverse">Undoing…</p>
```

## Good to know

- Keep it to a line or two. A shimmering paragraph is tiring to read.
- Put the text in a `role="status"` region when it changes, so the new step is announced. The shimmer itself is decoration.
- For placeholder blocks rather than text, use [Skeleton](https://hextaui.com/docs/skeleton), which shimmers surfaces with the theme's `animate-shimmer`.

## API reference

| Class | Description |
| --- | --- |
| `shimmer` | Sweeps a highlight across the text, every 2s. |
| `shimmer-once` | Sweeps once instead of repeating. |
| `shimmer-reverse` | Sweeps in the opposite direction. |
| `shimmer-none` | Turns it off, for example at a breakpoint. |
| `shimmer-color-<color>` | Color of the highlight, from the theme or arbitrary. Takes an opacity modifier. |
| `shimmer-duration-<ms>` | Length of one sweep in milliseconds. |
| `shimmer-spread-<number>` | Width of the band on the spacing scale, or any length. Defaults to 3ch + 40px. |
| `shimmer-angle-<deg>` | Tilt of the band. Defaults to 20°. |