# Introduction

Source: https://desyne.dev/docs

> Accessible React components built on React Aria, styled with shadcn tokens, installed as source you own.

Desyne is a copy-paste component library for React. Every component is built on
[React Aria Components](https://react-aria.adobe.com/) and styled with Tailwind CSS v4
using the same CSS variables as [shadcn/ui](https://ui.shadcn.com) (`--background`,
`--primary`, `--border`, …). You install components with the shadcn CLI, and they land
in your repo as plain `.tsx` files.

```tsx title="dialog/demo.tsx"
"use client";

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { TextField } from "@/components/ui/text-field";

export default function DialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline">Edit profile</Button>
      <DialogContent>
        {({ close }) => (
          <Form
            className="grid gap-5"
            onSubmit={(e) => {
              e.preventDefault();
              close();
            }}
          >
            <DialogHeader>
              <DialogTitle>Edit profile</DialogTitle>
              <DialogDescription>
                Update how your name appears to your team.
              </DialogDescription>
            </DialogHeader>
            <div className="grid gap-4">
              <TextField
                label="Name"
                defaultValue="Nischal Timalsina"
                autoFocus
              />
              <TextField label="Username" prefix="@" defaultValue="nischal" />
            </div>
            <DialogFooter>
              <DialogClose>Cancel</DialogClose>
              <Button type="submit">Save changes</Button>
            </DialogFooter>
          </Form>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}
```

## What you get

* **Accessible behaviour out of the box.** Keyboard navigation, focus management,
  screen reader announcements and ARIA patterns come from React Aria, not from
  hand-written `onKeyDown` handlers.
* **Your code, not a dependency.** The CLI copies source into `components/ui`. There is
  no `@desyne/*` package to upgrade and nothing you can't change.
* **shadcn-compatible tokens.** Components read the standard shadcn variables, so they
  inherit an existing shadcn theme and sit next to shadcn components without clashing.
* **One design language.** Controls share a 28 / 32 / 40px height scale, one focus ring,
  one field system and one tone system, so screens stay consistent as they grow.
* **Real examples.** Every component page has live previews you can copy, including
  recipes that combine several components into a working pattern.

## How it fits together

| Piece              | What it is                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------- |
| Components         | `components/ui/*.tsx`, one file per component, installed by name                          |
| `lib/utils.ts`     | shadcn's `cn()` helper (`clsx` + `tailwind-merge`)                                        |
| `lib/primitive.ts` | Shared helpers: the focus ring, the `tones` color system and `composeTailwindRenderProps` |
| Tokens             | CSS variables with shadcn names, plus `--brand`, `--success`, `--warning` and `--info`    |
| Registry           | A shadcn registry at `/r/{name}.json` under the `@desyne` namespace                       |

Components style React Aria states with Tailwind's native data variants
(`data-hovered:`, `data-pressed:`, `data-focus-visible:`, `data-selected:`,
`data-invalid:`), so you don't need a Tailwind plugin.

## Requirements

* React 19
* Tailwind CSS v4
* TypeScript (recommended; the source is typed)
* Any React framework: Next.js, Vite, React Router or TanStack Start

## Acknowledgements

Desyne stands on the work of others, and we're grateful for it:

* **[React Aria Components](https://react-aria.adobe.com/)** by Adobe. Every interactive
  component is built on its primitives, and the accessibility, keyboard and
  internationalisation behaviour you get comes from that work.
* **[shadcn/ui](https://ui.shadcn.com)** by shadcn. The copy-the-source model, the CLI and
  registry format we install through, and the token names we theme with all come from
  shadcn/ui.
* **[Intent UI](https://intentui.com)** by Irsyad A. Panjaitan. It showed what a polished,
  React Aria–based take on the shadcn approach can look like, and inspired parts of our
  component APIs, block catalogue and docs.

We also rely on [Tailwind CSS](https://tailwindcss.com), [Lucide](https://lucide.dev),
[Recharts](https://recharts.org), [Motion](https://motion.dev) and
[Fumadocs](https://fumadocs.dev). If you like Desyne, go star their repos too.

## Where to next

<Cards>
  <Card title="Installation" href="/docs/installation" description="Set up a Next.js, Vite or existing shadcn project." />

  <Card title="Theming" href="/docs/theming" description="Tokens, brand colors, radius, density and dark mode." />

  <Card title="Accessibility" href="/docs/accessibility" description="What React Aria handles for you, and what you still own." />

  <Card title="Components" href="/docs/components" description="Every component, with live previews and code." />

  <Card title="Forms & validation" href="/docs/forms" description="Native validation, server errors and Zod." />

  <Card title="AI & llms.txt" href="/docs/ai" description="Give your editor or assistant the whole library as Markdown." />
</Cards>

---

# Installation

Source: https://desyne.dev/docs/installation

> Set up Desyne in a Next.js, Vite or existing shadcn project, in a monorepo, or by copying files by hand.

Desyne installs through the [shadcn CLI](https://ui.shadcn.com/docs/cli). The CLI
reads the registry, copies component source into your project, installs npm
dependencies and adds any CSS variables a component needs.

<Callout title="Requirements">
  React 19, Tailwind CSS v4 and a `@/*` import alias. Components import
  `@/lib/utils`, `@/lib/primitive` and `@/components/ui/*`, the same paths a
  shadcn project already uses.
</Callout>

## Pick your setup

<Tabs items="[&#x22;Next.js&#x22;, &#x22;Vite&#x22;, &#x22;Existing shadcn project&#x22;]">
  <Tab value="Next.js">
    <Steps>
      <Step>
        ### Create the app

        ```bash
        npx create-next-app@latest my-app --typescript --tailwind --app
        cd my-app
        ```
      </Step>

      <Step>
        ### Initialise shadcn

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

        This writes `components.json`, `lib/utils.ts` and the base tokens in `app/globals.css`.
      </Step>

      <Step>
        ### Register the namespace

        Add the Desyne registry to `components.json`:

        ```json title="components.json"
        {
          "registries": {
            "@desyne": "https://desyne.dev/r/{name}.json"
          }
        }
        ```
      </Step>

      <Step>
        ### Add a component

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

        ```tsx title="app/page.tsx"
        import { Button } from "@/components/ui/button";

        export default function Page() {
          return <Button onPress={() => alert("Hello")}>Click me</Button>;
        }
        ```

        Components that use hooks or React Aria are marked `"use client"`, so they work in
        App Router pages without extra wrappers. See [Server components](/docs/server-components).
      </Step>
    </Steps>
  </Tab>

  <Tab value="Vite">
    <Steps>
      <Step>
        ### Create the app

        ```bash
        npm create vite@latest my-app -- --template react-ts
        cd my-app
        npm install tailwindcss @tailwindcss/vite
        ```

        Replace `src/index.css` with:

        ```css title="src/index.css"
        @import "tailwindcss";
        ```
      </Step>

      <Step>
        ### Add the `@` alias

        shadcn needs a path alias in both TypeScript and Vite.

        ```json title="tsconfig.json"
        {
          "files": [],
          "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }],
          "compilerOptions": {
            "baseUrl": ".",
            "paths": { "@/*": ["./src/*"] }
          }
        }
        ```

        Add the same `baseUrl` and `paths` to `tsconfig.app.json`, then:

        ```ts title="vite.config.ts"
        import path from "node:path";
        import tailwindcss from "@tailwindcss/vite";
        import react from "@vitejs/plugin-react";
        import { defineConfig } from "vite";

        export default defineConfig({
          plugins: [react(), tailwindcss()],
          resolve: {
            alias: { "@": path.resolve(__dirname, "./src") },
          },
        });
        ```
      </Step>

      <Step>
        ### Initialise shadcn and register the namespace

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

        ```json title="components.json"
        {
          "registries": {
            "@desyne": "https://desyne.dev/r/{name}.json"
          }
        }
        ```
      </Step>

      <Step>
        ### Add components

        ```bash
        npx shadcn@latest add @desyne/button @desyne/text-field
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab value="Existing shadcn project">
    Desyne components use the same token names and import paths as shadcn/ui, so they
    drop into an existing project.

    1. Add the namespace to `components.json`:

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

    2. Add components by their namespaced name:

       ```bash
       npx shadcn@latest add @desyne/select
       ```

    3. Your existing theme applies immediately. The first component that needs it also
       installs `lib/primitive.ts` and adds the extra tokens (`--brand`, `--success`,
       `--warning`, `--info`, `--destructive-foreground`) to your CSS.

    <Callout type="warn" title="Name clashes">
      Desyne and shadcn/ui both write to `components/ui/<name>.tsx`. Adding
      `@desyne/button` over an existing shadcn `button.tsx` asks before
      overwriting. Desyne's Button accepts shadcn's variant names (`default`,
      `destructive`, `secondary`, `outline`, `ghost`, `link`), but it is a React Aria
      button: handlers take `onPress`, and `disabled` is `isDisabled`. Check call sites
      before you replace a component.
    </Callout>
  </Tab>
</Tabs>

## Monorepos

In a Turborepo or pnpm/Bun workspace, keep components in a shared package and point
each app at it.

1. Run `npx shadcn@latest init` in the shared UI package and in each app, so every
   workspace has its own `components.json` with the `@desyne` registry entry.

2. Install into the shared package with `--cwd` (`-c`):

   ```bash
   npx shadcn@latest add @desyne/dialog -c packages/ui
   ```

3. In each app, map the aliases the components import to the shared package:

   ```json title="apps/web/tsconfig.json"
   {
     "compilerOptions": {
       "paths": {
         "@/components/ui/*": ["../../packages/ui/src/components/ui/*"],
         "@/lib/utils": ["../../packages/ui/src/lib/utils"],
         "@/lib/primitive": ["../../packages/ui/src/lib/primitive"],
         "@/*": ["./*"]
       }
     }
   }
   ```

4. Tell Tailwind to scan the package and, in Next.js, transpile it:

   ```css title="apps/web/app/globals.css"
   @import "tailwindcss";
   @source "../../../packages/ui/src";
   ```

   ```js title="apps/web/next.config.mjs"
   export default { transpilePackages: ["@acme/ui"] };
   ```

This is exactly how this documentation site consumes the library.

## Manual installation

You can skip the CLI and copy files yourself. Every component page has a **Manual** tab
with its source, its npm dependencies and the other components it imports.

<Steps>
  <Step>
    ### Install the shared dependencies

    ```bash
    npm install react-aria-components tailwind-variants clsx tailwind-merge lucide-react tw-animate-css
    ```

    Some components need more (`sonner` for Toast, `recharts` for Chart,
    `embla-carousel-react` for Carousel, `input-otp` for Input OTP). Their pages list them.
  </Step>

  <Step>
    ### Add the helpers

    ```ts title="lib/utils.ts"
    import { type ClassValue, clsx } from "clsx";
    import { twMerge } from "tailwind-merge";

    export function cn(...inputs: ClassValue[]) {
      return twMerge(clsx(inputs));
    }
    ```

    Then copy `lib/primitive.ts` from the [registry](/r/primitive.json) (the `files[0].content`
    field) or from any component's Manual tab.
  </Step>

  <Step>
    ### Add the tokens

    Your global CSS needs Tailwind, the animation utilities and the tokens:

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

    @custom-variant dark (&:is(.dark *));

    :root {
      --radius: 0.625rem;
      --background: oklch(0.984 0.002 286);
      --foreground: oklch(0.205 0.006 286);
      /* …the rest of the tokens */
    }
    ```

    The full set, with dark values and the `@theme inline` mapping, is on
    [Colors & tokens](/docs/colors).
  </Step>

  <Step>
    ### Copy components

    Copy each component into `components/ui/` and fix the imports if your aliases differ.
  </Step>
</Steps>

## Check it works

```tsx
"use client";

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { TextField } from "@/components/ui/text-field";

export function Smoke() {
  return (
    <Form className="flex max-w-xs flex-col gap-4">
      <TextField label="Email" name="email" type="email" isRequired />
      <Button type="submit">Subscribe</Button>
    </Form>
  );
}
```

Tab to the field: you should see the soft colored focus ring. Submit it empty: focus
moves to the field and the required-field message appears under it.

## Next steps

<Cards>
  <Card title="CLI & registry" href="/docs/cli" description="Namespaces, updates and the private Pro registry." />

  <Card title="Project structure" href="/docs/project-structure" description="Where files land and what each one does." />

  <Card title="Theming" href="/docs/theming" description="Make it look like your product." />
</Cards>

---

# CLI & registry

Source: https://desyne.dev/docs/cli

> How the @desyne namespace works, what the CLI writes, how to update components, and how to connect the private Pro registry.

Desyne is distributed as a [shadcn registry](https://ui.shadcn.com/docs/registry): a
set of JSON files, one per item, served at `/r/{name}.json`. The shadcn CLI fetches an
item, copies its files into your project, installs its npm dependencies, follows its
`registryDependencies` and merges any CSS variables it declares.

## Namespaces

Registries are configured in `components.json` under `registries`. The key is the
namespace you type on the command line; the value is a URL template where `{name}` is
replaced by the item name.

```json title="components.json"
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "tsx": true,
  "tailwind": { "css": "app/globals.css", "baseColor": "neutral", "cssVariables": true },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@desyne": "https://desyne.dev/r/{name}.json"
  }
}
```

| Namespace     | Contents                       | Access                                           |
| ------------- | ------------------------------ | ------------------------------------------------ |
| `@desyne`     | Components and `lib/primitive` | Public                                           |
| `@desyne-pro` | Pro blocks                     | License key ([below](#the-private-pro-registry)) |

## Commands

```bash
# Add one or more components
npx shadcn@latest add @desyne/button @desyne/dialog

# Inspect an item before installing it (files, dependencies, CSS)
npx shadcn@latest view @desyne/date-picker

# Search the namespace
npx shadcn@latest search @desyne -q date

# Install straight from a URL, no namespace needed
npx shadcn@latest add https://desyne.dev/r/combobox.json
```

## What an item contains

Each component item lists its source file, npm dependencies and the other registry
items it imports. Dependencies are inferred from the source, so they are always in
sync with the code.

```json title="/r/text-field.json (abridged)"
{
  "name": "text-field",
  "type": "registry:ui",
  "title": "Text Field",
  "dependencies": ["react-aria-components"],
  "registryDependencies": ["@desyne/field", "@desyne/primitive"],
  "files": [{ "path": "components/ui/text-field.tsx", "type": "registry:ui" }]
}
```

Adding `text-field` therefore also installs `field.tsx` and `lib/primitive.ts`, and
`primitive` in turn depends on shadcn's own `utils` item (`lib/utils.ts`).

### The `primitive` item

`lib/primitive.ts` is the only shared library file. It exports:

* `composeTailwindRenderProps(className, tw)`: merges a React Aria `className` (a string or a render-prop function) with Tailwind classes.
* `focusRing`: the keyboard focus style, a 3px glow in `--ring` on `data-focus-visible`.
* `tones` and the `Tone` type: the color system behind every `color` prop ([Theming](/docs/theming#tones)).

The item also carries `cssVars`, so the first install adds `--brand`, `--success`,
`--warning`, `--info` and `--destructive-foreground` (light and dark) to your CSS and
maps them to Tailwind colors.

## Updating components

Installed components are your code, so the CLI never updates them behind your back. To
pull a newer version:

<Steps>
  <Step>
    Commit or stash your work so you can review the change.
  </Step>

  <Step>
    Re-add the component with `--overwrite`:

    ```bash
    npx shadcn@latest add @desyne/select --overwrite
    ```
  </Step>

  <Step>
    Review the diff with `git diff` and re-apply any local edits you want to keep.
  </Step>
</Steps>

<Callout title="Keep local changes small">
  Prefer passing `className`, wrapping a component, or adding a variant over
  rewriting internals. Small, local edits survive updates with an easy merge.
  The [Changelog](/changelog) lists what changed in each release.
</Callout>

## The private Pro registry

Pro blocks are served from the Pro site's own registry, which checks a license key on
every request. Keys look like `dsp_` followed by 32 characters; you'll find yours on
your account page after purchase.

<Steps>
  <Step>
    ### Store the key in an environment variable

    ```bash title=".env.local"
    DESYNE_PRO_LICENSE=dsp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```

    Never commit the key. In CI, add it as a secret with the same name.
  </Step>

  <Step>
    ### Add the registry with an Authorization header

    ```json title="components.json"
    {
      "registries": {
        "@desyne": "https://desyne.dev/r/{name}.json",
        "@desyne-pro": {
          "url": "https://pro.desyne.dev/r/{name}.json",
          "headers": {
            "Authorization": "Bearer ${DESYNE_PRO_LICENSE}"
          }
        }
      }
    }
    ```

    The CLI expands `${DESYNE_PRO_LICENSE}` from your environment and `.env` files when it makes
    the request.
  </Step>

  <Step>
    ### Install blocks by name

    ```bash
    npx shadcn@latest add @desyne-pro/pricing-02
    ```

    Block files land in `components/blocks/<name>/`, and the components they use come from
    `@desyne` automatically.
  </Step>
</Steps>

| Response | Meaning                                                                                  |
| -------- | ---------------------------------------------------------------------------------------- |
| `200`    | The block JSON, with file contents                                                       |
| `401`    | Missing, invalid or inactive key. Check the variable is set in the shell running the CLI |
| `404`    | No block with that name                                                                  |

A handful of blocks are free teasers and install without a key. See
[Installing blocks](/docs/pro/blocks) for the full workflow.

---

# Project structure

Source: https://desyne.dev/docs/project-structure

> Where Desyne files land in your project, what each one does, and how to organise your own code around them.

After `init` and a few `add` commands, a Next.js project looks like this:

```txt
app/
  globals.css          Tailwind, tw-animate-css and the tokens
  layout.tsx           Root layout: providers, <Toaster />
components/
  ui/                  Desyne components, one file each
    button.tsx
    field.tsx          Shared by every text-like control
    text-field.tsx
    dialog.tsx
    …
  blocks/              Pro blocks, one folder each (if you use Pro)
    pricing-02/
lib/
  utils.ts             cn(): clsx + tailwind-merge
  primitive.ts         focusRing, tones, composeTailwindRenderProps
components.json        shadcn config and registry namespaces
```

In Vite the same tree lives under `src/`.

## The files

| File                      | Role                                                                                                                                                                                                   | Edit it?                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| `components/ui/*.tsx`     | Component source. Each file exports the component, its parts and usually a `*Variants` function built with `tailwind-variants`                                                                         | Yes. It's yours                            |
| `components/ui/field.tsx` | `Label`, `Description`, `FieldError`, `FieldGroup`, `Input` and `fieldVariants` (outline, filled, underlined × sm, md, lg). Text Field, Select, Combobox, Number Field and the date fields build on it | Yes, and the change applies to every field |
| `lib/primitive.ts`        | Focus ring, tones and the render-prop class helper                                                                                                                                                     | Rarely. Add a tone here                    |
| `lib/utils.ts`            | shadcn's `cn()`                                                                                                                                                                                        | No need                                    |
| `app/globals.css`         | Tokens and Tailwind setup                                                                                                                                                                              | Yes. This is where theming happens         |

## Anatomy of a component

Components follow one pattern, so once you've read one you can read them all:

```tsx title="components/ui/switch.tsx (shape)"
"use client";

import { Switch as SwitchPrimitive } from "react-aria-components";
import { tv } from "tailwind-variants";
import { composeTailwindRenderProps } from "@/lib/primitive";

// 1. Styles: a tv() recipe with variants and sizes, using data-* state variants
const switchVariants = tv({ /* … */ });

// 2. Props: the React Aria props plus our style props
export interface SwitchProps extends SwitchPrimitiveProps { /* … */ }

// 3. Component: the React Aria primitive with classes applied
export function Switch({ className, ...props }: SwitchProps) {
  return (
    <SwitchPrimitive
      data-slot="switch"
      {...props}
      className={composeTailwindRenderProps(className, "group flex items-center gap-2")}
    />
  );
}
```

* **`data-slot`** attributes name each part (`data-slot="dialog-content"`), so you can
  target parts from a parent: `[&_[data-slot=card-header]]:pb-0`.
* **State styling** uses React Aria's data attributes: `data-hovered:`, `data-pressed:`,
  `data-focus-visible:`, `data-selected:`, `data-disabled:`, `data-invalid:`,
  `data-entering:` and `data-exiting:`. Group variants (`group-data-invalid/field:`)
  style children from a parent's state.
* **`className`** accepts a string or a function of render props, like every React
  Aria component: `className={({ isSelected }) => isSelected ? "font-semibold" : ""}`.

## Organising your own code

Keep `components/ui` for primitives and put product code beside it:

```txt
components/
  ui/                  Desyne (and any shadcn) primitives
  blocks/              Pro blocks you've installed
  settings/            Your feature components, composed from ui/
    notifications.tsx
```

When you need a variation that every screen should share, edit the primitive. When only
one screen needs it, wrap the primitive in a feature component instead. That keeps
`components/ui` easy to update with `--overwrite` (see [CLI & registry](/docs/cli#updating-components)).

---

# Theming

Source: https://desyne.dev/docs/theming

> shadcn token names, an ink primary with an indigo brand accent, color tones, radius and density, dark mode and multiple themes.

Every component reads CSS variables with shadcn's names, so theming is a CSS job: change
values in `globals.css` and every component follows. There's no theme provider and no
JavaScript involved.

The default theme is "enterprise-crisp": layered neutral surfaces, an **ink** primary for
the main action, an **indigo brand** accent for selection, focus and links, a 10px base
radius and compact 28 / 32 / 40px controls.

## How the tokens are used

| Token                                                | Used for                                                                                     |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `--background` / `--foreground`                      | Page canvas and body text                                                                    |
| `--card`, `--popover`                                | Raised surfaces: cards, menus, dialogs, popovers                                             |
| `--primary` / `--primary-foreground`                 | Solid buttons and the main call to action                                                    |
| `--brand` / `--brand-foreground`                     | Selection and emphasis: checked checkboxes, switches, radios, selected tabs and dates, links |
| `--secondary`, `--muted` / `--muted-foreground`      | Quiet fills, inset panels and secondary text                                                 |
| `--accent` / `--accent-foreground`                   | Hovered and highlighted items in lists and menus                                             |
| `--destructive` / `--destructive-foreground`         | Errors, invalid fields and destructive actions                                               |
| `--success`, `--warning`, `--info` (+ `-foreground`) | Status colors used by tones                                                                  |
| `--border`, `--input`                                | Hairlines and field outlines                                                                 |
| `--ring`                                             | Focus glow (`ring-ring/25`) and the focused-field border                                     |
| `--radius`                                           | Base radius that the whole radius scale derives from                                         |
| `--chart-1` … `--chart-5`                            | Chart series                                                                                 |
| `--sidebar-*`                                        | The Sidebar component's own surface set                                                      |

The full list with default values is on [Colors & tokens](/docs/colors).

## Build a brand theme

Most products only need three changes: the brand color, the primary action color and
the radius.

```css title="app/globals.css"
:root {
  --brand: oklch(0.56 0.14 160);            /* emerald */
  --brand-foreground: oklch(0.99 0 0);
  --ring: oklch(0.56 0.14 160);

  --primary: oklch(0.56 0.14 160);          /* make solid buttons brand-colored too */
  --primary-foreground: oklch(0.99 0 0);

  --radius: 0.5rem;
}

.dark {
  --brand: oklch(0.72 0.14 160);
  --ring: oklch(0.72 0.14 160);
  --primary: oklch(0.72 0.14 160);
  --primary-foreground: oklch(0.2 0.05 160);
}
```

Tips that keep a theme looking finished:

* **Use OKLCH.** Equal lightness steps look equal, so a dark-mode brand is usually the
  same hue and chroma with lightness raised by about 0.12–0.18.
* **Tint the neutrals.** The default neutrals carry a trace of the brand hue (`286`).
  Change the hue on `--background`, `--muted`, `--border` and friends to match your
  brand and keep chroma below `0.01`.
* **Keep `--ring` close to `--brand`.** The focus glow is the brand color at 25%
  opacity, which reads as part of the design rather than a browser default.
* **Check contrast.** Text on `--primary` and `--brand` should reach 4.5:1. Amber and
  yellow brands usually need a dark `-foreground`.

<Callout title="Ink or brand primary?">
  The default keeps `--primary` near-black so the main action stands out without
  competing with selected states. If your brand is the action color, set `--primary`
  to the brand value as above.
</Callout>

## Tones

Components with a `color` prop (Button, Badge, Alert, Tag Group, Slider, Progress Bar,
Progress Circle, Meter, Spinner, Rating, Timeline) share one tone system. A tone is a
class that sets two variables, `--tone` and `--tone-fg`, and the variant styles are
written against them:

```ts title="lib/primitive.ts"
export const tones = {
  primary: "[--tone-fg:var(--primary-foreground)] [--tone:var(--primary)]",
  brand: "[--tone-fg:var(--brand-foreground)] [--tone:var(--brand)]",
  neutral: "[--tone-fg:var(--background)] [--tone:var(--foreground)]",
  danger: "[--tone-fg:var(--destructive-foreground)] [--tone:var(--destructive)]",
  success: "[--tone-fg:var(--success-foreground)] [--tone:var(--success)]",
  warning: "[--tone-fg:var(--warning-foreground)] [--tone:var(--warning)]",
  info: "[--tone-fg:var(--info-foreground)] [--tone:var(--info)]",
} as const;
```

So the soft style is `bg-(--tone)/10 text-(--tone)` for every color, and one variant
definition covers all seven.

```tsx
<Button color="brand">Deploy</Button>
<Button variant="soft" color="danger">Delete</Button>
<Badge color="success" variant="soft">Live</Badge>
<Alert color="warning">Your trial ends in 3 days.</Alert>
```

### Add a tone

<Steps>
  <Step>
    Define the color in your CSS and expose it to Tailwind:

    ```css title="app/globals.css"
    :root { --violet: oklch(0.55 0.22 300); --violet-foreground: oklch(0.99 0 0); }
    .dark { --violet: oklch(0.7 0.18 300); --violet-foreground: oklch(0.2 0.05 300); }

    @theme inline {
      --color-violet: var(--violet);
      --color-violet-foreground: var(--violet-foreground);
    }
    ```
  </Step>

  <Step>
    Add it to `tones`:

    ```ts title="lib/primitive.ts"
    export const tones = {
      // …
      violet: "[--tone-fg:var(--violet-foreground)] [--tone:var(--violet)]",
    } as const;
    ```
  </Step>

  <Step>
    Add it to the `color` variant of the components that should accept it, for example in
    `button.tsx`:

    ```ts
    color: {
      // …
      violet: tones.violet,
    },
    ```

    `Tone` is derived from `tones`, so the prop types update automatically.
  </Step>
</Steps>

## Radius

One variable drives the whole scale, defined in the `@theme inline` block:

| Utility      | Value            | Used by                        |
| ------------ | ---------------- | ------------------------------ |
| `rounded-xs` | `--radius` − 6px | Tiny details                   |
| `rounded-sm` | `--radius` − 4px | `xs` buttons, small tags       |
| `rounded-md` | `--radius` − 2px | Buttons, fields, menu items    |
| `rounded-lg` | `--radius`       | Popovers, menus and list boxes |
| `rounded-xl` | `--radius` + 4px | Cards and dialogs              |

With the default `--radius: 0.625rem`, controls are 8px, popovers 10px and cards 14px. Set
`--radius: 0.375rem` for a sharper look or `0.875rem` for a softer one; the steps
keep their relationship because they all derive from the same base. (Checkboxes keep a
fixed 4px corner.)

## Density

Controls share one height scale so mixed rows line up:

| Size           | Height | Use it for                                        |
| -------------- | ------ | ------------------------------------------------- |
| `sm`           | 28px   | Toolbars, table filters, dense settings           |
| `md` (default) | 32px   | Most forms and dialogs                            |
| `lg`           | 40px   | Marketing pages, touch-first and onboarding flows |

```tsx
<div className="flex items-end gap-2">
  <SearchField size="sm" aria-label="Filter" />
  <Select size="sm" aria-label="Status">…</Select>
  <Button size="sm">Apply</Button>
</div>
```

Text-like fields also take a `variant`: `outline` (default), `filled` or `underlined`.
For larger regions, Card takes `size` (`sm`, `md`, `lg`) and Table takes `density`
(`compact`, `default`, `comfortable`).

## Theme builder & styles

The [theme builder](/themes) puts every token on one page: pick a **style**, a **base**
neutral, a **brand** color (a preset or any custom color), the **radius**, **density** and
**font**, and watch a live dashboard of real components update. Share the result as a link
(`/themes?design=…`) or apply it to the previews on this site.

| Style   | Character                                                    | Defaults                           |
| ------- | ------------------------------------------------------------ | ---------------------------------- |
| Default | Crisp hairlines, soft depth and medium radii                 | 0.625rem · default density · Inter |
| Soft    | Rounder shapes, filled fields, gentle diffused shadows       | 0.875rem · default · Inter         |
| Sharp   | Square corners, hairline borders, dense controls, no shadows | 0.25rem · compact · Geist          |
| Bold    | Thick borders, strong contrast, chunky controls, heavy type  | 0.5rem · comfortable · Inter       |

A style is a set of structural tokens: radius levels (`--radius-control`, `--radius-box`,
`--radius-overlay`…), `--border-width`, field chrome (`--field-bg`, `--field-border`),
shadows, `--ring-width` and heading weights. Picking a style resets radius, density and font
to that style's defaults and keeps your base and brand. Bases are neutral palettes (zinc,
neutral, slate, stone, olive, mauve); the brand drives `--brand`, `--ring` and `--chart-1`,
with the dark-mode variant and the text color on it derived for you.

### Install a theme

Press **Install** in the builder to get a command for your design. It points at a
`registry:theme` item that the shadcn CLI merges into your global CSS (`:root`, `.dark`
and the font stack in `@theme inline`):

```bash
npx shadcn@latest add https://<your-docs-host>/r/themes/1~soft~zinc~indigo~0.875~default~inter.json
```

The **CSS** tab gives the same variables to paste by hand. Components read only tokens,
so the ones you've already installed pick up a new theme without being reinstalled. If the
theme uses a font other than Inter, load that font too (the CLI adds a Google Fonts
`@import`; with Next.js you can use `next/font` instead).

## Dark mode

Dark values live under a `.dark` class, and the tokens file declares a class-based
`dark:` variant. Put `class="dark"` on `<html>` (or any ancestor) and everything inside
switches. See [Dark mode](/docs/dark-mode) for the toggle and `next-themes` setup.

## Multiple themes

Because themes are just variables, you can scope one to any element.

```css title="app/globals.css"
[data-theme="ocean"] {
  --brand: oklch(0.6 0.13 230);
  --ring: oklch(0.6 0.13 230);
  --radius: 1rem;
}
.dark [data-theme="ocean"],
[data-theme="ocean"].dark {
  --brand: oklch(0.74 0.12 230);
  --ring: oklch(0.74 0.12 230);
}
```

```tsx
<html data-theme="ocean">…</html>              {/* whole app */}
<section data-theme="ocean">…</section>        {/* one area, e.g. a customer's portal */}
```

You can also set variables inline for a live preview, the way the theme studio on the
home page does:

```tsx
<div style={{ "--brand": accent, "--radius": "1rem" } as React.CSSProperties}>
  <Checkbox defaultSelected>Uses the preview accent</Checkbox>
</div>
```

<Callout type="warn" title="Popovers render in a portal">
  Menus, popovers, dialogs and toasts render at the end of `<body>`, outside the
  element where you scoped a theme. Put theme attributes on `<html>` or `<body>` when
  overlays should match, or wrap the portal content in its own themed element.
</Callout>

---

# Colors & tokens

Source: https://desyne.dev/docs/colors

> Every design token with its light and dark value, the Tailwind utilities it maps to, and the complete CSS to paste into a project.

Tokens use [shadcn's names](https://ui.shadcn.com/docs/theming) and OKLCH values. Each
token is exposed to Tailwind as a color through `@theme inline`, so `--brand` becomes
`bg-brand`, `text-brand`, `border-brand`, `ring-brand` and so on, with opacity
modifiers like `bg-brand/10`.

<Callout title="Source of truth">
  These values come from `theme.css` in the library. The swatches show the live values
  on this site, so toggle the site theme to compare light and dark.
</Callout>

## Color tokens

### Surfaces

|                                       | Token                  | Light                    | Dark                     |
| ------------------------------------- | ---------------------- | ------------------------ | ------------------------ |
| <Swatch token="background" />         | `--background`         | `oklch(0.984 0.002 286)` | `oklch(0.145 0.004 286)` |
| <Swatch token="foreground" />         | `--foreground`         | `oklch(0.205 0.006 286)` | `oklch(0.97 0.002 286)`  |
| <Swatch token="card" />               | `--card`               | `oklch(1 0 0)`           | `oklch(0.185 0.005 286)` |
| <Swatch token="card-foreground" />    | `--card-foreground`    | `oklch(0.205 0.006 286)` | `oklch(0.97 0.002 286)`  |
| <Swatch token="popover" />            | `--popover`            | `oklch(1 0 0)`           | `oklch(0.205 0.006 286)` |
| <Swatch token="popover-foreground" /> | `--popover-foreground` | `oklch(0.205 0.006 286)` | `oklch(0.97 0.002 286)`  |

### Actions and emphasis

|                                         | Token                    | Light                    | Dark                     |
| --------------------------------------- | ------------------------ | ------------------------ | ------------------------ |
| <Swatch token="primary" />              | `--primary`              | `oklch(0.215 0.006 286)` | `oklch(0.965 0.002 286)` |
| <Swatch token="primary-foreground" />   | `--primary-foreground`   | `oklch(0.985 0 0)`       | `oklch(0.2 0.006 286)`   |
| <Swatch token="brand" />                | `--brand`                | `oklch(0.54 0.21 277)`   | `oklch(0.67 0.18 277)`   |
| <Swatch token="brand-foreground" />     | `--brand-foreground`     | `oklch(0.99 0.005 277)`  | `oklch(0.99 0.005 277)`  |
| <Swatch token="secondary" />            | `--secondary`            | `oklch(0.967 0.002 286)` | `oklch(0.235 0.006 286)` |
| <Swatch token="secondary-foreground" /> | `--secondary-foreground` | `oklch(0.25 0.006 286)`  | `oklch(0.95 0.002 286)`  |
| <Swatch token="muted" />                | `--muted`                | `oklch(0.967 0.002 286)` | `oklch(0.225 0.006 286)` |
| <Swatch token="muted-foreground" />     | `--muted-foreground`     | `oklch(0.54 0.012 286)`  | `oklch(0.7 0.012 286)`   |
| <Swatch token="accent" />               | `--accent`               | `oklch(0.955 0.003 286)` | `oklch(0.255 0.006 286)` |
| <Swatch token="accent-foreground" />    | `--accent-foreground`    | `oklch(0.205 0.006 286)` | `oklch(0.97 0.002 286)`  |

### Status

|                                           | Token                      | Light                  | Dark                   |
| ----------------------------------------- | -------------------------- | ---------------------- | ---------------------- |
| <Swatch token="destructive" />            | `--destructive`            | `oklch(0.585 0.22 25)` | `oklch(0.66 0.2 22)`   |
| <Swatch token="destructive-foreground" /> | `--destructive-foreground` | `oklch(0.99 0 0)`      | `oklch(0.99 0 0)`      |
| <Swatch token="success" />                | `--success`                | `oklch(0.62 0.16 150)` | `oklch(0.72 0.15 150)` |
| <Swatch token="success-foreground" />     | `--success-foreground`     | `oklch(0.99 0 0)`      | `oklch(0.2 0.05 150)`  |
| <Swatch token="warning" />                | `--warning`                | `oklch(0.76 0.16 70)`  | `oklch(0.8 0.15 75)`   |
| <Swatch token="warning-foreground" />     | `--warning-foreground`     | `oklch(0.25 0.06 70)`  | `oklch(0.25 0.06 70)`  |
| <Swatch token="info" />                   | `--info`                   | `oklch(0.6 0.16 240)`  | `oklch(0.7 0.14 240)`  |
| <Swatch token="info-foreground" />        | `--info-foreground`        | `oklch(0.99 0 0)`      | `oklch(0.2 0.05 240)`  |

### Lines and focus

|                           | Token      | Light                    | Dark                   |
| ------------------------- | ---------- | ------------------------ | ---------------------- |
| <Swatch token="border" /> | `--border` | `oklch(0.925 0.003 286)` | `oklch(1 0 0 / 8%)`    |
| <Swatch token="input" />  | `--input`  | `oklch(0.895 0.004 286)` | `oklch(1 0 0 / 13%)`   |
| <Swatch token="ring" />   | `--ring`   | `oklch(0.54 0.21 277)`   | `oklch(0.67 0.18 277)` |

### Charts

|                            | Token       | Light                  | Dark                   |
| -------------------------- | ----------- | ---------------------- | ---------------------- |
| <Swatch token="chart-1" /> | `--chart-1` | `oklch(0.54 0.21 277)` | `oklch(0.67 0.18 277)` |
| <Swatch token="chart-2" /> | `--chart-2` | `oklch(0.7 0.13 185)`  | `oklch(0.74 0.12 185)` |
| <Swatch token="chart-3" /> | `--chart-3` | `oklch(0.78 0.15 75)`  | `oklch(0.8 0.14 75)`   |
| <Swatch token="chart-4" /> | `--chart-4` | `oklch(0.65 0.2 350)`  | `oklch(0.7 0.18 350)`  |
| <Swatch token="chart-5" /> | `--chart-5` | `oklch(0.7 0.12 235)`  | `oklch(0.74 0.12 235)` |

### Sidebar

|                                               | Token                          | Light                    | Dark                     |
| --------------------------------------------- | ------------------------------ | ------------------------ | ------------------------ |
| <Swatch token="sidebar" />                    | `--sidebar`                    | `oklch(0.975 0.002 286)` | `oklch(0.165 0.005 286)` |
| <Swatch token="sidebar-foreground" />         | `--sidebar-foreground`         | `oklch(0.205 0.006 286)` | `oklch(0.97 0.002 286)`  |
| <Swatch token="sidebar-primary" />            | `--sidebar-primary`            | `oklch(0.215 0.006 286)` | `oklch(0.965 0.002 286)` |
| <Swatch token="sidebar-primary-foreground" /> | `--sidebar-primary-foreground` | `oklch(0.985 0 0)`       | `oklch(0.2 0.006 286)`   |
| <Swatch token="sidebar-accent" />             | `--sidebar-accent`             | `oklch(1 0 0)`           | `oklch(0.225 0.006 286)` |
| <Swatch token="sidebar-accent-foreground" />  | `--sidebar-accent-foreground`  | `oklch(0.205 0.006 286)` | `oklch(0.97 0.002 286)`  |
| <Swatch token="sidebar-border" />             | `--sidebar-border`             | `oklch(0.925 0.003 286)` | `oklch(1 0 0 / 8%)`      |
| <Swatch token="sidebar-ring" />               | `--sidebar-ring`               | `oklch(0.54 0.21 277)`   | `oklch(0.67 0.18 277)`   |

Neutrals use hue `286` with very low chroma, which gives the grays a faint cool tint
that matches the indigo brand. In dark mode, `--border` and `--input` are translucent
white, so they adapt to whatever surface they sit on.

## Radius

| Token      | Default    | Utilities                                                                                        |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `--radius` | `0.625rem` | `rounded-xs` (−6px), `rounded-sm` (−4px), `rounded-md` (−2px), `rounded-lg`, `rounded-xl` (+4px) |

## Additive tokens

shadcn/ui doesn't define these. When you install a component through the CLI, the
`primitive` item adds them to your CSS automatically:

| Token                               | Purpose                               |
| ----------------------------------- | ------------------------------------- |
| `--brand`, `--brand-foreground`     | Accent for selection, focus and links |
| `--destructive-foreground`          | Text on solid destructive fills       |
| `--success`, `--success-foreground` | Positive states                       |
| `--warning`, `--warning-foreground` | Caution states                        |
| `--info`, `--info-foreground`       | Neutral information                   |

## Using tokens in your own code

```tsx
// Utilities
<div className="rounded-xl border bg-card p-4 text-card-foreground" />
<p className="text-muted-foreground text-sm" />
<span className="bg-brand/10 text-brand" />

// Arbitrary values for anything without a utility
<div className="shadow-[0_0_0_4px_color-mix(in_oklab,var(--brand)_20%,transparent)]" />
```

Prefer semantic tokens over raw palette colors (`bg-card`, not `bg-white`). Semantic
tokens switch with dark mode and with any theme you scope to an element.

## The complete CSS

Paste this into your global stylesheet when you aren't using `shadcn init`, or when you
want Desyne's default look instead of your current shadcn theme.

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

@custom-variant dark (&:is(.dark *));

:root {
  --radius: 0.625rem;

  /* Surfaces: canvas < card (white) ; muted = inset panels inside cards */
  --background: oklch(0.984 0.002 286);
  --foreground: oklch(0.205 0.006 286);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.205 0.006 286);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.205 0.006 286);

  /* Ink primary for the main action; brand (indigo) for selection, focus, links */
  --primary: oklch(0.215 0.006 286);
  --primary-foreground: oklch(0.985 0 0);
  --brand: oklch(0.54 0.21 277);
  --brand-foreground: oklch(0.99 0.005 277);
  --secondary: oklch(0.967 0.002 286);
  --secondary-foreground: oklch(0.25 0.006 286);
  --muted: oklch(0.967 0.002 286);
  --muted-foreground: oklch(0.54 0.012 286);
  --accent: oklch(0.955 0.003 286);
  --accent-foreground: oklch(0.205 0.006 286);

  --destructive: oklch(0.585 0.22 25);
  --destructive-foreground: oklch(0.99 0 0);
  --success: oklch(0.62 0.16 150);
  --success-foreground: oklch(0.99 0 0);
  --warning: oklch(0.76 0.16 70);
  --warning-foreground: oklch(0.25 0.06 70);
  --info: oklch(0.6 0.16 240);
  --info-foreground: oklch(0.99 0 0);

  --border: oklch(0.925 0.003 286);
  --input: oklch(0.895 0.004 286);
  --ring: oklch(0.54 0.21 277);

  --chart-1: oklch(0.54 0.21 277);
  --chart-2: oklch(0.7 0.13 185);
  --chart-3: oklch(0.78 0.15 75);
  --chart-4: oklch(0.65 0.2 350);
  --chart-5: oklch(0.7 0.12 235);

  --sidebar: oklch(0.975 0.002 286);
  --sidebar-foreground: oklch(0.205 0.006 286);
  --sidebar-primary: oklch(0.215 0.006 286);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(1 0 0);
  --sidebar-accent-foreground: oklch(0.205 0.006 286);
  --sidebar-border: oklch(0.925 0.003 286);
  --sidebar-ring: oklch(0.54 0.21 277);
}

.dark {
  --background: oklch(0.145 0.004 286);
  --foreground: oklch(0.97 0.002 286);
  --card: oklch(0.185 0.005 286);
  --card-foreground: oklch(0.97 0.002 286);
  --popover: oklch(0.205 0.006 286);
  --popover-foreground: oklch(0.97 0.002 286);

  --primary: oklch(0.965 0.002 286);
  --primary-foreground: oklch(0.2 0.006 286);
  --brand: oklch(0.67 0.18 277);
  --brand-foreground: oklch(0.99 0.005 277);
  --secondary: oklch(0.235 0.006 286);
  --secondary-foreground: oklch(0.95 0.002 286);
  --muted: oklch(0.225 0.006 286);
  --muted-foreground: oklch(0.7 0.012 286);
  --accent: oklch(0.255 0.006 286);
  --accent-foreground: oklch(0.97 0.002 286);

  --destructive: oklch(0.66 0.2 22);
  --destructive-foreground: oklch(0.99 0 0);
  --success: oklch(0.72 0.15 150);
  --success-foreground: oklch(0.2 0.05 150);
  --warning: oklch(0.8 0.15 75);
  --warning-foreground: oklch(0.25 0.06 70);
  --info: oklch(0.7 0.14 240);
  --info-foreground: oklch(0.2 0.05 240);

  --border: oklch(1 0 0 / 8%);
  --input: oklch(1 0 0 / 13%);
  --ring: oklch(0.67 0.18 277);

  --chart-1: oklch(0.67 0.18 277);
  --chart-2: oklch(0.74 0.12 185);
  --chart-3: oklch(0.8 0.14 75);
  --chart-4: oklch(0.7 0.18 350);
  --chart-5: oklch(0.74 0.12 235);

  --sidebar: oklch(0.165 0.005 286);
  --sidebar-foreground: oklch(0.97 0.002 286);
  --sidebar-primary: oklch(0.965 0.002 286);
  --sidebar-primary-foreground: oklch(0.2 0.006 286);
  --sidebar-accent: oklch(0.225 0.006 286);
  --sidebar-accent-foreground: oklch(0.97 0.002 286);
  --sidebar-border: oklch(1 0 0 / 8%);
  --sidebar-ring: oklch(0.67 0.18 277);
}

@theme inline {
  --radius-xs: calc(var(--radius) - 6px);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-success: var(--success);
  --color-success-foreground: var(--success-foreground);
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground antialiased;
  }
}
```

---

# Typography

Source: https://desyne.dev/docs/typography

> Fonts, the text scale components use, and how to style headings and long-form content.

Components don't ship a font. They inherit `font-family` from your page and use
Tailwind's text scale, so the type system is whatever your app sets on `<body>`.

<Callout title="Typography component">
  For headings, body text, lists, inline code and long-form content, use the
  [Typography](/docs/components/typography) component. It renders plain elements
  with no `"use client"`, so it works in server components.
</Callout>

## Set a font

The examples, blocks and templates use [Inter](https://rsms.me/inter/) through
`next/font`, exposed as Tailwind's `--font-sans`:

```tsx title="app/layout.tsx"
import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"], variable: "--font-sans" });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.variable} suppressHydrationWarning>
      <body className="font-sans antialiased">{children}</body>
    </html>
  );
}
```

```css title="app/globals.css"
@theme inline {
  --font-sans: var(--font-sans), ui-sans-serif, system-ui, sans-serif;
}
```

Any neutral sans works. Fonts with tabular figures (Inter, Geist, IBM Plex Sans) suit
data-heavy screens: tables and stats in the library use `tabular-nums`.

## The scale components use

| Where                                             | Class                     | Size     |
| ------------------------------------------------- | ------------------------- | -------- |
| Buttons, fields, menu items, table cells (`md`)   | `text-sm`                 | 14px     |
| `sm` controls, badges, descriptions, field errors | `text-xs`                 | 12px     |
| `lg` controls                                     | `text-base`               | 16px     |
| Dialog titles                                     | `text-base font-semibold` | 16px     |
| Card titles                                       | `text-sm font-medium`     | 14px     |
| Keyboard shortcuts, code                          | `font-mono`               | inherits |

Body copy sits at 14px in dense product UI. For reading-heavy pages, set a larger base
on the page container (`text-base`) and leave controls at their own sizes.

## Hierarchy without extra sizes

Most screens need only three levels: a title, body text and muted secondary text.

```tsx
<div className="grid gap-1">
  <h2 className="font-semibold text-lg tracking-tight">Billing</h2>
  <p className="text-muted-foreground text-sm">
    Manage your plan, payment method and invoices.
  </p>
</div>
```

* Use `text-muted-foreground` for secondary text instead of a smaller size.
* Use `tracking-tight` on headings 18px and larger.
* Use `text-balance` on headings and `text-pretty` on paragraphs to avoid orphans.
* Keep line length around 60–75 characters (`max-w-prose`) for long text.

## Labels and descriptions

Form text comes from `field.tsx`, so all fields match:

| Part          | Style                                                            |
| ------------- | ---------------------------------------------------------------- |
| `Label`       | `text-sm font-medium`, with a red `*` when the field is required |
| `Description` | `text-xs text-muted-foreground`                                  |
| `FieldError`  | `text-xs text-destructive`                                       |

Change those once in `field.tsx` to restyle every form.

---

# Dark mode

Source: https://desyne.dev/docs/dark-mode

> Class-based dark mode with next-themes, a theme toggle, and how to preview or force a mode for part of a page.

Every token has a dark value under the `.dark` selector, and the tokens file declares a
class-based variant:

```css
@custom-variant dark (&:is(.dark *));
```

So dark mode is on wherever an ancestor has `class="dark"`. Components never check the
mode in JavaScript, which means no flash, no context and no re-render when it changes.

## Next.js with next-themes

[next-themes](https://github.com/pacocoursey/next-themes) toggles the class on `<html>`,
follows the system setting and remembers the choice.

```bash
npm install next-themes
```

```tsx title="app/providers.tsx"
"use client";

import { ThemeProvider } from "next-themes";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider
      attribute="class"
      defaultTheme="system"
      enableSystem
      disableTransitionOnChange
    >
      {children}
    </ThemeProvider>
  );
}
```

```tsx title="app/layout.tsx"
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

`suppressHydrationWarning` is needed because next-themes sets the class before React
hydrates. `disableTransitionOnChange` stops every color transition from animating at once
when the mode flips.

## A theme toggle

```tsx title="components/theme-toggle.tsx"
"use client";

import { MonitorIcon, MoonIcon, SunIcon } from "lucide-react";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";

export function ThemeToggle() {
  const { theme = "system", setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null; // the theme is unknown on the server

  return (
    <ToggleButtonGroup
      aria-label="Theme"
      variant="segmented"
      size="sm"
      disallowEmptySelection
      selectedKeys={[theme]}
      onSelectionChange={(keys) => setTheme(String([...keys][0]))}
    >
      <ToggleButton id="light" aria-label="Light"><SunIcon /></ToggleButton>
      <ToggleButton id="system" aria-label="System"><MonitorIcon /></ToggleButton>
      <ToggleButton id="dark" aria-label="Dark"><MoonIcon /></ToggleButton>
    </ToggleButtonGroup>
  );
}
```

For a single button, a `Button` with `variant="ghost" size="icon"` calling
`setTheme(resolvedTheme === "dark" ? "light" : "dark")` works too. Give it an
`aria-label`.

## Vite and other setups

Without next-themes, set the class yourself before first paint so there's no flash:

```html title="index.html"
<script>
  const stored = localStorage.getItem("theme");
  const dark = stored ? stored === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
  document.documentElement.classList.toggle("dark", dark);
</script>
```

Then toggle `document.documentElement.classList` and write `localStorage.theme` from
your toggle.

## Forcing a mode for part of a page

Because the variant matches descendants of `.dark`, you can render one region dark on a
light page. The final call-to-action on the home page does exactly this:

```tsx
<section className="dark rounded-3xl bg-background p-12 text-foreground">
  <h2>Ship the next screen this afternoon.</h2>
  <Button color="brand">Get started</Button>
</section>
```

Inside the section, `bg-background` and every component use dark tokens. To force light
inside a dark page, re-declare the light values on a class such as `.light` in your CSS.

## Writing dark-aware styles

* Prefer tokens (`bg-card`, `border-border`) over `dark:` overrides. Tokens already
  switch.
* Use `dark:` for the few things tokens can't express, such as removing a shadow that
  disappears on dark surfaces: `shadow-sm dark:shadow-none`.
* Images and screenshots need two sources. Toggle them with `dark:hidden` and
  `hidden dark:block`.
* Set the browser's own UI to match with `color-scheme`:

```css
:root { color-scheme: light; }
.dark { color-scheme: dark; }
```

---

# Icons

Source: https://desyne.dev/docs/icons

> Lucide icons by default, automatic sizing inside components, and labelling icon-only controls.

Components use [Lucide](https://lucide.dev) (`lucide-react`) for their built-in icons
(chevrons, checks, close buttons) and the examples use it throughout. Any React icon
set that renders an `<svg>` works.

```bash
npm install lucide-react
```

## Sizing is automatic

Components size icon children for you. Button, for example, applies
`[&_svg:not([class*='size-'])]:size-4`, so an icon picks up the right size for the
button's size unless you set one:

| Button size                   | Icon size |
| ----------------------------- | --------- |
| `xs`, `icon-xs`               | 12px      |
| `sm`, `icon-sm`               | 14px      |
| `md`, `lg`, `icon`, `icon-lg` | 16px      |

```tsx
import { PlusIcon } from "lucide-react";

<Button><PlusIcon /> New project</Button>          {/* 16px */}
<Button size="sm"><PlusIcon /> New</Button>        {/* 14px */}
<Button><PlusIcon className="size-5" /> Big</Button> {/* your size wins */}
```

Menu items, select items, tabs, badges, alerts, card titles and field addons do the
same, and they also handle spacing and muted color. Don't add margins to icons; the
parent's `gap` spaces them.

## Icon-only controls need a label

An icon is invisible to screen readers. Give the control an accessible name:

```tsx
import { TrashIcon } from "lucide-react";

<Button variant="ghost" size="icon" aria-label="Delete file">
  <TrashIcon />
</Button>
```

Pair it with a tooltip so sighted mouse users get the same information:

```tsx
<TooltipTrigger>
  <Button variant="ghost" size="icon" aria-label="Delete file">
    <TrashIcon />
  </Button>
  <Tooltip>Delete file</Tooltip>
</TooltipTrigger>
```

The tooltip doesn't replace `aria-label`: tooltips only show on hover and keyboard
focus, never on touch.

## Decorative icons

When an icon sits next to text that already says the same thing, it's decorative.
Lucide icons render as plain `<svg>` without a title, and React Aria computes the
control's name from its text, so the icon adds nothing to the announcement. For
standalone decorative icons, add `aria-hidden`:

```tsx
<p className="flex items-center gap-2 text-muted-foreground text-sm">
  <InfoIcon aria-hidden className="size-4" />
  Changes are saved automatically.
</p>
```

## Field prefixes and suffixes

Text fields, selects and the input group take icons as `prefix` and `suffix`:

```tsx
import { AtSignIcon, UserIcon } from "lucide-react";

<TextField label="Email" prefix={<AtSignIcon />} placeholder="you@company.com" />
<Select label="Owner" prefix={<UserIcon />}>…</Select>
```

## Using another icon set

Swap the imports in the component files. Built-in icons live in a handful of places:
`ChevronDownIcon` in Select, `ChevronsUpDownIcon` in Combobox, `CheckIcon` in Checkbox
and list items, `XIcon` in Dialog (Sheet reuses its close button) and Tag, `ChevronLeftIcon`/`ChevronRightIcon` in Calendar and
Pagination, `Loader2Icon` for pending buttons. Search the folder for `lucide-react` to
find them all.

---

# Motion & reduced motion

Source: https://desyne.dev/docs/motion

> How overlays animate with React Aria's entering and exiting states, the animation utilities components use, and how reduced motion is respected.

Motion in Desyne is short, functional and CSS-only. Overlays fade and scale in,
panels slide, progress moves smoothly, and everything settles in 150–200ms. There's no
animation library in the components.

## Entering and exiting

React Aria keeps an overlay mounted while it animates out and exposes the phase as
data attributes: `data-entering` while it opens and `data-exiting` while it closes.
Components pair those with the [tw-animate-css](https://github.com/Wombosvideo/tw-animate-css)
utilities:

```tsx title="components/ui/popover.tsx (excerpt)"
"data-entering:fade-in-0 data-entering:zoom-in-[0.97] data-entering:animate-in data-entering:duration-150",
"data-exiting:fade-out-0 data-exiting:zoom-out-[0.97] data-exiting:animate-out data-exiting:duration-100",
```

| Component                            | Motion                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| Dialog                               | Overlay fades; panel fades, scales from 97% and rises 8px (200ms in, 150ms out) |
| Sheet                                | Slides in from its side (300ms in, 200ms out)                                   |
| Popover, Menu, Select, Combobox      | Fade and scale from 97% (150ms in, 100ms out)                                   |
| Tooltip                              | Fade and scale from 95% (100ms)                                                 |
| Disclosure                           | Height transition on the panel                                                  |
| Progress Bar, Progress Circle, Meter | Value transitions; indeterminate bar sweeps                                     |
| Skeleton                             | Pulse or shimmer                                                                |
| Toast                                | Sonner's slide and stack                                                        |

`tw-animate-css` must be imported once in your global CSS:

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

`shadcn init` adds this line for you.

### Animating your own overlays

Use the same attributes on any React Aria overlay:

```tsx
import { Modal, ModalOverlay } from "react-aria-components";

<ModalOverlay className="fixed inset-0 bg-black/40 data-entering:animate-in data-entering:fade-in-0 data-exiting:animate-out data-exiting:fade-out-0">
  <Modal className="data-entering:animate-in data-entering:slide-in-from-bottom-4 data-exiting:animate-out data-exiting:slide-out-to-bottom-4">
    …
  </Modal>
</ModalOverlay>
```

React Aria waits for the exit animation to finish before unmounting, so you don't need
`AnimatePresence` or timeouts.

## Reduced motion

People who turn on **Reduce motion** in their OS get a calmer interface. Components
that move continuously use Tailwind's `motion-reduce:` variant:

| Component                     | Under reduced motion                                  |
| ----------------------------- | ----------------------------------------------------- |
| Spinner                       | Stops rotating and gently pulses instead              |
| Progress Bar (indeterminate)  | Becomes a full-width pulse instead of a sweep         |
| Progress Bar, Progress Circle | Value changes jump instead of easing                  |
| Skeleton                      | Pulse and shimmer are removed, leaving a static block |
| Disclosure                    | Opens and closes without the height transition        |
| Toast loading icon            | Stops spinning                                        |

Short fades on overlays are kept: they help people track where content came from and
don't involve large movement.

### In your own code

```tsx
// Remove decorative motion
<div className="animate-[float_6s_ease-in-out_infinite] motion-reduce:animate-none" />

// Swap movement for opacity
<div className="transition-transform hover:-translate-y-1 motion-reduce:transition-opacity motion-reduce:hover:translate-y-0" />
```

For JavaScript-driven animation (Motion, GSAP, canvas), read the preference:

```tsx
import { useEffect, useState } from "react";

export function usePrefersReducedMotion() {
  const [reduced, setReduced] = useState(false);
  useEffect(() => {
    const query = matchMedia("(prefers-reduced-motion: reduce)");
    setReduced(query.matches);
    const onChange = () => setReduced(query.matches);
    query.addEventListener("change", onChange);
    return () => query.removeEventListener("change", onChange);
  }, []);
  return reduced;
}
```

If you use [Motion](https://motion.dev), `<MotionConfig reducedMotion="user">` does
this for every animation in the tree. The Pro templates use that setup.

## Guidelines

* Keep UI transitions between 100 and 250ms. Exits faster than entrances.
* Animate `opacity` and `transform`. Avoid animating layout properties on large areas.
* Never make information depend on motion. A pulsing badge also needs text.
* Marquees and auto-advancing carousels need a pause control and should stop under
  reduced motion.

---

# Accessibility

Source: https://desyne.dev/docs/accessibility

> What React Aria gives every component, the keyboard model, focus and screen reader behaviour, what you still own, and how to test it.

Every interactive component is built on [React Aria Components](https://react-aria.adobe.com/),
Adobe's library of accessible primitives. Desyne adds styling; the behaviour (roles,
keyboard interaction, focus management, announcements) comes from React Aria, which is
tested across browsers, screen readers and input methods.

## What you get for free

| Area                 | What React Aria handles                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Semantics            | Correct roles and ARIA attributes for each pattern: `listbox`, `menu`, `grid`, `dialog`, `tablist`, `slider` and so on    |
| Labelling            | `label`, `description` and `errorMessage` props are wired to the control with `aria-labelledby` and `aria-describedby`    |
| Keyboard             | Arrow keys, Home/End, Page Up/Down, typeahead and Escape, following the WAI-ARIA patterns                                 |
| Focus                | Focus trapping in modals, focus restore on close, roving focus in collections, focus-visible detection                    |
| Interactions         | `onPress` normalises mouse, touch, pen and keyboard; hover styles don't stick on touch devices                            |
| Announcements        | Live-region messages for things like combobox results and drag and drop                                                   |
| Validation           | Native and custom errors exposed to assistive tech and linked to the field                                                |
| Internationalisation | Right-to-left keyboard behaviour, localised date and number parts. See [Internationalisation](/docs/internationalization) |

## Focus

The focus ring only appears for keyboard users. React Aria sets `data-focus-visible`
when focus arrives from the keyboard, and components style that state:

```ts title="lib/primitive.ts"
export const focusRing =
  "outline-none data-focus-visible:ring-[3px] data-focus-visible:ring-ring/25";
```

Fields show focus on the group (`data-focus-within`) with a brand-colored border and
glow, so the ring wraps prefixes and suffixes too.

<Callout type="warn" title="Don't remove the ring">
  If you restyle a component, keep a visible `data-focus-visible` style with at least
  3:1 contrast against the background. Change its color with `--ring`.
</Callout>

**Overlays manage focus for you.** A Dialog or Sheet moves focus inside when it opens,
keeps Tab inside while open, closes on Escape and returns focus to the trigger. Use
`autoFocus` on a field to choose where focus starts:

```tsx
<DialogContent>
  <DialogHeader>
    <DialogTitle>Rename project</DialogTitle>
  </DialogHeader>
  <TextField label="Name" defaultValue="Atlas" autoFocus />
</DialogContent>
```

## Keyboard reference

| Component                        | Keys                                                                                                                                    |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Button, Toggle Button, Link      | <kbd>Enter</kbd> / <kbd>Space</kbd> activate                                                                                            |
| Checkbox, Switch                 | <kbd>Space</kbd> toggles                                                                                                                |
| Radio Group, Toggle Button Group | <kbd>Arrow</kbd> keys move and select; <kbd>Tab</kbd> leaves the group                                                                  |
| Tabs                             | <kbd>Arrow</kbd> keys move between tabs; <kbd>Home</kbd> / <kbd>End</kbd> jump                                                          |
| Menu                             | <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>↓</kbd> open; arrows move; type to jump; <kbd>Esc</kbd> closes; <kbd>→</kbd> opens a submenu |
| Select                           | <kbd>Space</kbd> / <kbd>Enter</kbd> / arrows open; type to jump to an option                                                            |
| Combobox                         | Type to filter; <kbd>↓</kbd> opens; <kbd>Enter</kbd> selects; <kbd>Esc</kbd> closes, then clears                                        |
| Slider                           | Arrows step; <kbd>Page Up</kbd> / <kbd>Page Down</kbd> take bigger steps; <kbd>Home</kbd> / <kbd>End</kbd> go to min / max              |
| Number Field                     | <kbd>↑</kbd> / <kbd>↓</kbd> step; <kbd>Page Up</kbd> / <kbd>Page Down</kbd> step by 10×                                                 |
| Date Field, Time Field           | <kbd>←</kbd> / <kbd>→</kbd> move between segments; <kbd>↑</kbd> / <kbd>↓</kbd> change a segment; digits type into it                    |
| Calendar                         | Arrows move by day and week; <kbd>Page Up</kbd> / <kbd>Page Down</kbd> by month; with <kbd>Shift</kbd> by year                          |
| Table, Grid List, List Box       | Arrows move; <kbd>Space</kbd> selects; <kbd>Shift</kbd> + arrows extend a selection; <kbd>Ctrl/⌘</kbd> + <kbd>A</kbd> selects all       |
| Tag Group                        | Arrows move; <kbd>Delete</kbd> / <kbd>Backspace</kbd> remove a removable tag                                                            |
| Disclosure                       | <kbd>Enter</kbd> / <kbd>Space</kbd> expand and collapse                                                                                 |
| Dialog, Sheet, Popover           | <kbd>Esc</kbd> closes (not for `role="alertdialog"`); <kbd>Tab</kbd> stays inside                                                       |
| Toast                            | <kbd>Alt</kbd> + <kbd>T</kbd> moves focus to the toast region                                                                           |

## Screen readers

Components announce the right thing as long as each control has a name.

* **Prefer visible labels.** Pass `label` to fields. It renders a real `<label>`
  linked to the input.
* **Name controls without a visible label** with `aria-label`: icon-only buttons,
  search fields in toolbars, sliders in compact layouts.
* **Name collections and groups.** Tables, list boxes, tag groups, radio groups and
  toggle groups need `aria-label` (or a `label`) so users know what they're in.
* **Write good descriptions.** `description` is read after the label; keep it to one
  short sentence.
* **Announce async results.** Use `toast()` for confirmations and background results;
  the toast region is a live region.

```tsx
<SearchField aria-label="Search invoices" size="sm" />

<Table aria-label="Invoices" selectionMode="multiple">…</Table>

<ToggleButtonGroup aria-label="Text alignment">…</ToggleButtonGroup>
```

## What you still own

React Aria makes each component accessible. A page also needs:

* **Structure.** One `<h1>`, headings in order, and landmarks (`<header>`, `<nav>`,
  `<main>`, `<footer>`).
* **Contrast.** The default tokens meet WCAG AA for text. If you change `--primary`,
  `--brand` or `--muted-foreground`, re-check text at 4.5:1 and UI parts at 3:1.
* **Text alternatives.** `alt` on meaningful images, `alt=""` on decorative ones.
* **Link and button text** that makes sense out of context ("Download invoice", not
  "Click here").
* **Target size.** The smallest controls (`xs`, 24px) meet WCAG 2.2's 24×24px minimum.
  Use `md` or `lg` sizes for primary actions on touch screens.
* **Errors you can find.** For long forms, move focus to the first invalid field on
  submit (React Aria's `Form` does this for native validation) or show a summary.
* **No nested interactive elements.** Don't put a button inside a clickable card; use
  the card's own `href` or a single link that covers it.

## Testing

### By hand (5 minutes per screen)

1. Unplug the mouse. Tab through the page: is the order logical, is focus always
   visible, can you reach and operate everything?
2. Open and close every overlay with the keyboard. Does focus return to where it was?
3. Zoom to 200% and check nothing overlaps or is cut off.
4. Turn on a screen reader (VoiceOver: <kbd>⌘</kbd> + <kbd>F5</kbd>; NVDA on Windows) and
   move through the main flow. Does every control announce a name, role and state?

### Automated

[axe-core](https://github.com/dequelabs/axe-core) catches missing names, contrast issues
and invalid ARIA. Run it in end-to-end tests:

```ts title="e2e/a11y.spec.ts"
import AxeBuilder from "@axe-core/playwright";
import { expect, test } from "@playwright/test";

test("settings page has no detectable a11y violations", async ({ page }) => {
  await page.goto("/settings");
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});
```

Test behaviour the way users reach it, by role and name, with
[Testing Library](https://testing-library.com):

```tsx title="plan-select.test.tsx"
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Select, SelectItem } from "@/components/ui/select";

test("picks a plan with the keyboard", async () => {
  const user = userEvent.setup();
  render(
    <Select label="Plan" placeholder="Choose a plan">
      <SelectItem id="free">Free</SelectItem>
      <SelectItem id="pro">Pro</SelectItem>
    </Select>,
  );

  await user.tab();
  await user.keyboard("{ArrowDown}");
  await user.click(screen.getByRole("option", { name: "Pro" }));

  expect(screen.getByRole("button", { name: /Plan/ })).toHaveTextContent("Pro");
});
```

Automated tools find roughly a third of issues. Keep the manual pass.

---

# Internationalisation

Source: https://desyne.dev/docs/internationalization

> Locales, right-to-left layouts, dates, times, numbers and calendars, all handled by React Aria's I18nProvider and @internationalized/date.

React Aria formats and parses dates, times and numbers for the user's locale, mirrors
keyboard navigation in right-to-left languages and ships translated strings for its
built-in labels (such as "Next month" or "Clear search") in 30+ languages.

## Setting the locale

By default React Aria uses the browser's language. To set it explicitly, for example
from your router or user settings, wrap the app in `I18nProvider`:

```tsx title="app/[lang]/layout.tsx"
import { I18nProvider } from "react-aria-components";

export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ lang: string }>;
}) {
  const { lang } = await params;
  return (
    <html lang={lang} dir={rtlLocales.has(lang.split("-")[0]) ? "rtl" : "ltr"}>
      <body>
        <I18nProvider locale={lang}>{children}</I18nProvider>
      </body>
    </html>
  );
}

const rtlLocales = new Set(["ar", "fa", "he", "ur"]);
```

`I18nProvider` is a client component; using it in a server layout is fine because its
children stay server-rendered.

<Callout title="Server rendering">
  On the server there's no browser language, so React Aria falls back to `en-US`.
  Set `I18nProvider` from the request (route segment, cookie or `Accept-Language`)
  to avoid a hydration mismatch in date and number output.
</Callout>

You can also nest providers to localise one part of a page:

```tsx
<I18nProvider locale="de-DE">
  <DatePicker label="Lieferdatum" />
</I18nProvider>
```

## Right-to-left

Set `dir="rtl"` on `<html>` (as above) so the browser lays out text right to left.
React Aria reads the locale's direction and mirrors keyboard behaviour: in Arabic or
Hebrew, <kbd>→</kbd> moves to the previous item in tabs, radio groups and calendars, and
sliders fill from the right.

Tailwind handles layout through logical utilities. Some component spacing uses physical
classes (`pl-*`, `mr-*`), so check RTL screens and swap them for logical equivalents in
your copy where needed:

| Physical             | Logical             |
| -------------------- | ------------------- |
| `ml-2` / `mr-2`      | `ms-2` / `me-2`     |
| `pl-3` / `pr-3`      | `ps-3` / `pe-3`     |
| `left-0` / `right-0` | `start-0` / `end-0` |
| `text-left`          | `text-start`        |
| `rounded-l-md`       | `rounded-s-md`      |

Use the `rtl:` variant for anything that should flip visually, such as directional
icons: `<ChevronRightIcon className="rtl:rotate-180" />`.

## Dates and times

Date components use [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)
values instead of JavaScript `Date`, so a date is a calendar date with no hidden time
zone.

```bash
npm install @internationalized/date
```

```tsx
"use client";

import { getLocalTimeZone, parseDate, today } from "@internationalized/date";
import { useState } from "react";
import { DatePicker } from "@/components/ui/date-picker";

export function DueDate() {
  const [value, setValue] = useState(parseDate("2026-11-02"));
  return (
    <DatePicker
      label="Due date"
      value={value}
      onChange={(v) => v && setValue(v)}
      minValue={today(getLocalTimeZone())}
    />
  );
}
```

| Value type         | Create it with                                                     | Use for                  |
| ------------------ | ------------------------------------------------------------------ | ------------------------ |
| `CalendarDate`     | `parseDate("2026-11-02")`, `today(tz)`                             | Birthdays, due dates     |
| `CalendarDateTime` | `parseDateTime("2026-11-02T09:30")`                                | Local appointments       |
| `ZonedDateTime`    | `parseZonedDateTime("2026-11-02T09:30[Europe/Berlin]")`, `now(tz)` | Events across time zones |
| `Time`             | `parseTime("09:30")`                                               | Time Field               |

The field adapts to the locale: segment order (`dd.mm.yyyy` in German, `yyyy/mm/dd` in
Japanese), 12- or 24-hour time and the first day of the week. Override the week start
with `firstDayOfWeek="mon"`.

Convert at the edges of your app: `value.toString()` gives an ISO string for your API,
and `value.toDate(getLocalTimeZone())` gives a `Date` when a library needs one.

### Other calendars

Add a Unicode calendar extension to the locale and the Calendar, Date Field and Date
Picker render in that system while your value stays convertible:

```tsx
<I18nProvider locale="th-TH-u-ca-buddhist">
  <Calendar aria-label="Date" />
</I18nProvider>
```

Try the Arabic, Japanese imperial and Thai Buddhist locales in the
[Calendar locales example](/docs/components/calendar).

## Numbers

Number Field formats with `Intl.NumberFormat` options and parses what users type in
their locale, including the decimal separator:

```tsx
<NumberField label="Price" defaultValue={1299.5}
  formatOptions={{ style: "currency", currency: "EUR" }} />

<NumberField label="Discount" defaultValue={0.15}
  formatOptions={{ style: "percent" }} />

<NumberField label="Weight" defaultValue={12}
  formatOptions={{ style: "unit", unit: "kilogram" }} />
```

In `de-DE` the first one reads "1.299,50 €"; in `en-US`, "€1,299.50".

For display-only numbers and dates, use React Aria's formatter hooks so output matches
the provider's locale:

```tsx
"use client";

import { useDateFormatter, useNumberFormatter } from "react-aria";

export function Total({ amount, paidAt }: { amount: number; paidAt: Date }) {
  const money = useNumberFormatter({ style: "currency", currency: "USD" });
  const date = useDateFormatter({ dateStyle: "medium" });
  return <p>{money.format(amount)} paid on {date.format(paidAt)}</p>;
}
```

`react-aria` is a separate package from `react-aria-components`; install it if you use
these hooks.

## Your own strings

React Aria translates its built-in strings only. Your labels, placeholders and
messages come from your app, so pass them through your i18n library (next-intl,
react-i18next, Lingui) like any other text:

```tsx
<TextField label={t("billing.email")} errorMessage={t("errors.email")} />
```

---

# Forms & validation

Source: https://desyne.dev/docs/forms

> Build forms with React Aria's Form, native and custom validation, server errors, Zod schemas and Next.js server actions.

Fields in Desyne are React Aria fields with a label, description and error built in.
Put them in React Aria's `Form` and you get native HTML validation, accessible error
messages and focus on the first invalid field, with no form library.

## A basic form

```tsx title="components/signup-form.tsx"
"use client";

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { TextField } from "@/components/ui/text-field";

export function SignupForm() {
  return (
    <Form
      className="flex max-w-sm flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();
        const data = Object.fromEntries(new FormData(e.currentTarget));
        console.log(data); // { name, email, terms }
      }}
    >
      <TextField label="Name" name="name" autoComplete="name" isRequired />
      <TextField
        label="Work email"
        name="email"
        type="email"
        autoComplete="email"
        description="We'll send the invite here."
        isRequired
      />
      <Checkbox name="terms" value="yes" isRequired>
        I agree to the terms
      </Checkbox>
      <Button type="submit">Create account</Button>
    </Form>
  );
}
```

Every field takes a `name`, so `FormData` works as in plain HTML. Required fields get a
red asterisk on the label.

## How validation behaves

| Behaviour                                                                         | `validationBehavior="native"` (default)                    | `validationBehavior="aria"`            |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------- |
| Blocks submit when invalid                                                        | Yes                                                        | No; you decide                         |
| When errors show                                                                  | After the first submit attempt, then live as values change | Immediately, as values change          |
| Built-in rules (`isRequired`, `type="email"`, `minLength`, `pattern`, `minValue`) | Yes, with the browser's localised messages                 | Exposed as `aria-invalid`, no messages |
| Focus first invalid field on submit                                               | Yes                                                        | No                                     |

Set it on the `Form` to apply to every field, or on a single field.

## Custom rules

Use `validate` for rules that HTML can't express. Return a string (or an array of
strings) to mark the field invalid, or `null`/`true` when valid:

```tsx
<TextField
  label="Username"
  name="username"
  isRequired
  validate={(value) =>
    /^[a-z0-9-]{3,20}$/.test(value)
      ? null
      : "3–20 lowercase letters, numbers or dashes."
  }
/>
```

Override the browser's built-in messages with `errorMessage`, which also accepts a
function of the validation state:

```tsx
<TextField
  label="Email"
  type="email"
  isRequired
  errorMessage={({ validationDetails }) =>
    validationDetails.valueMissing ? "Enter your email." : "That doesn't look like an email."
  }
/>
```

## Server errors

Pass errors keyed by field `name` to `validationErrors`. They show immediately, and each
clears as soon as the user edits that field.

```tsx
"use client";

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { TextField } from "@/components/ui/text-field";

export function WorkspaceForm() {
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [pending, setPending] = useState(false);

  return (
    <Form
      validationErrors={errors}
      onSubmit={async (e) => {
        e.preventDefault();
        setPending(true);
        const res = await fetch("/api/workspaces", {
          method: "POST",
          body: new FormData(e.currentTarget),
        });
        setErrors(res.ok ? {} : (await res.json()).errors);
        setPending(false);
      }}
      className="flex max-w-sm flex-col gap-4"
    >
      <TextField label="Workspace name" name="name" isRequired />
      <TextField label="URL" name="slug" prefix="acme.app/" isRequired />
      <Button type="submit" isPending={pending}>
        Create workspace
      </Button>
    </Form>
  );
}
```

`isPending` shows a spinner in the button, keeps its width, and ignores further presses
while the request runs. See the live version in
[Text Field: server errors](/docs/components/text-field).

## With Zod

Validate on the server with a [Zod 4](https://zod.dev) schema and return its field errors
in the same shape:

```ts title="lib/schemas.ts"
import { z } from "zod";

export const inviteSchema = z.object({
  email: z.email("Enter a valid email."),
  role: z.enum(["admin", "member", "viewer"], { message: "Choose a role." }),
  seats: z.coerce.number().int().min(1).max(50),
});
```

```ts title="app/actions.ts"
"use server";

import { z } from "zod";
import { inviteSchema } from "@/lib/schemas";

export type InviteState = { errors: Record<string, string[]>; ok?: boolean };

export async function invite(_prev: InviteState, formData: FormData): Promise<InviteState> {
  const parsed = inviteSchema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) {
    return { errors: z.flattenError(parsed.error).fieldErrors as Record<string, string[]> };
  }
  // await db.invites.create(parsed.data)
  return { errors: {}, ok: true };
}
```

Wire it up with `useActionState`. React Aria accepts `string | string[]` per field:

```tsx title="app/invite-form.tsx"
"use client";

import { useActionState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";
import { Select, SelectItem } from "@/components/ui/select";
import { TextField } from "@/components/ui/text-field";
import { invite } from "./actions";

export function InviteForm() {
  const [state, action, pending] = useActionState(invite, { errors: {} });

  return (
    <Form action={action} validationErrors={state.errors} className="grid max-w-sm gap-4">
      <TextField label="Email" name="email" type="email" isRequired />
      <Select label="Role" name="role" isRequired placeholder="Choose a role">
        <SelectItem id="admin">Admin</SelectItem>
        <SelectItem id="member">Member</SelectItem>
        <SelectItem id="viewer">Viewer</SelectItem>
      </Select>
      <NumberField label="Seats" name="seats" defaultValue={1} minValue={1} maxValue={50} />
      <Button type="submit" isPending={pending}>Send invite</Button>
    </Form>
  );
}
```

Native rules (`isRequired`, `type="email"`, `minValue`) still run in the browser first,
so most mistakes never reach the server. The schema is the source of truth on the
server.

<Callout title="Client-side Zod">
  To validate with the same schema while typing, call `safeParse` on one field inside
  `validate`: `validate={(v) => inviteSchema.shape.email.safeParse(v).error?.issues[0]?.message}`.
</Callout>

## Other form libraries

React Hook Form, TanStack Form and Conform all work. Use controlled props
(`value`/`onChange`, or `isSelected` for checkboxes and `selectedKey` for selects) and
pass the library's error to `isInvalid` and `errorMessage`:

```tsx
import { Controller, useForm } from "react-hook-form";

const { control, handleSubmit } = useForm<{ email: string }>();

<Controller
  control={control}
  name="email"
  rules={{ required: "Enter your email." }}
  render={({ field, fieldState }) => (
    <TextField
      label="Email"
      value={field.value ?? ""}
      onChange={field.onChange}
      onBlur={field.onBlur}
      name={field.name}
      isInvalid={fieldState.invalid}
      errorMessage={fieldState.error?.message}
      validationBehavior="aria"
    />
  )}
/>
```

## Layout tips

* Stack fields with `gap-4`; group related fields under a heading and a `Separator`.
* Put two short fields side by side with `grid gap-4 sm:grid-cols-2`.
* Keep the primary button at the end and align it with the fields' left edge.
* Use `description` for format hints instead of placeholder text, which disappears.

---

# Data tables

Source: https://desyne.dev/docs/data-tables

> Build sortable, filterable, selectable and paginated tables with the Table component, React Aria's sort and selection state, and your own data logic.

`Table` is a styled React Aria table. React Aria handles the grid semantics, keyboard
navigation, row selection and sort announcements; you keep full control of the data.
There's no data-grid abstraction: sorting, filtering and paging are a few lines of
`useMemo` over your rows, or a request to your API.

The full result of this guide is the
[data table recipe](/docs/components/table), live.

## Columns and rows

```tsx
import { Cell, Column, Row, Table, TableBody, TableHeader } from "@/components/ui/table";

<Table aria-label="Invoices">
  <TableHeader>
    <Column id="id" isRowHeader>Invoice</Column>
    <Column id="customer">Customer</Column>
    <Column id="amount" className="text-right">Amount</Column>
  </TableHeader>
  <TableBody items={invoices}>
    {(inv) => (
      <Row>
        <Cell className="font-medium">{inv.id}</Cell>
        <Cell>{inv.customer}</Cell>
        <Cell className="text-right tabular-nums">{currency.format(inv.amount)}</Cell>
      </Row>
    )}
  </TableBody>
</Table>
```

* Give the table an `aria-label` (or `aria-labelledby` pointing at a heading).
* Mark one column `isRowHeader` so screen readers announce rows by that cell.
* Items need an `id` property (or pass `id` to `Row`) so selection and updates are stable.
* Right-align numbers and use `tabular-nums` so digits line up.

### Appearance

| Prop       | Values                              | Default   |
| ---------- | ----------------------------------- | --------- |
| `density`  | `compact`, `default`, `comfortable` | `default` |
| `striped`  | Zebra rows                          | `false`   |
| `bordered` | Grid lines between every cell       | `false`   |
| `framed`   | Wrap in a rounded, bordered card    | `true`    |

## Sorting

Hold a `SortDescriptor` in state, mark columns `allowsSorting`, and sort the rows:

```tsx
"use client";

import { useMemo, useState } from "react";
import type { SortDescriptor } from "react-aria-components";

const [sort, setSort] = useState<SortDescriptor>({ column: "issued", direction: "descending" });

const rows = useMemo(() => {
  const key = sort.column as keyof Invoice;
  return [...invoices].sort((a, b) => {
    const cmp =
      typeof a[key] === "number"
        ? (a[key] as number) - (b[key] as number)
        : String(a[key]).localeCompare(String(b[key]));
    return sort.direction === "descending" ? -cmp : cmp;
  });
}, [sort]);

<Table aria-label="Invoices" sortDescriptor={sort} onSortChange={setSort}>
  <TableHeader>
    <Column id="customer" isRowHeader allowsSorting>Customer</Column>
    <Column id="issued" allowsSorting>Issued</Column>
    <Column id="amount" allowsSorting className="text-right">Amount</Column>
  </TableHeader>
  <TableBody items={rows}>{/* … */}</TableBody>
</Table>
```

The column `id` is what arrives in `sort.column`. Headers get a sort indicator and
`aria-sort` automatically.

## Filtering and search

Filter before sorting, and reset to the first page when a filter changes:

```tsx
const [query, setQuery] = useState("");
const [status, setStatus] = useState<Key | null>("all");

const filtered = useMemo(() => {
  const q = query.trim().toLowerCase();
  return invoices.filter(
    (inv) =>
      (status === "all" || inv.status === status) &&
      (!q || inv.customer.toLowerCase().includes(q) || inv.id.toLowerCase().includes(q)),
  );
}, [query, status]);

<div className="flex flex-wrap items-center gap-2">
  <SearchField
    aria-label="Search invoices"
    placeholder="Search customer or invoice…"
    size="sm"
    value={query}
    onChange={(v) => { setQuery(v); setPage(1); }}
    className="min-w-48 flex-1"
  />
  <Select aria-label="Status" size="sm" selectedKey={status}
    onSelectionChange={(k) => { setStatus(k); setPage(1); }} className="w-40">
    <SelectItem id="all">All statuses</SelectItem>
    <SelectItem id="Paid">Paid</SelectItem>
    <SelectItem id="Overdue">Overdue</SelectItem>
  </Select>
</div>
```

`sm` controls (28px) keep the toolbar compact and aligned.

## Empty state

Render something useful when nothing matches:

```tsx
<TableBody items={rows} renderEmptyState={() => "No invoices match your filters."}>
  {(inv) => <Row>{/* … */}</Row>}
</TableBody>
```

## Selection and bulk actions

```tsx
const [selected, setSelected] = useState<Selection>(new Set());
const count = selected === "all" ? filtered.length : selected.size;

<Table
  aria-label="Invoices"
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={setSelected}
>
  …
</Table>
```

With `selectionMode="multiple"` the table adds a checkbox column and a select-all
checkbox in the header. `selected` is either a `Set` of row ids or the string `"all"`.
Swap the filter toolbar for bulk actions while rows are selected:

```tsx
{count > 0 ? (
  <div className="flex items-center gap-2">
    <span className="font-medium text-sm">{count} selected</span>
    <Button size="sm" variant="outline"><DownloadIcon /> Export</Button>
    <Button size="sm" variant="ghost" onPress={() => setSelected(new Set())}>Clear</Button>
  </div>
) : (
  <Toolbar />
)}
```

Use `selectionMode="single"` for master-detail layouts, and `selectionBehavior="replace"`
for file-manager style selection where clicking a row replaces the selection.

## Pagination

Slice the filtered rows and render a `Paginator`:

```tsx
import { Paginator } from "@/components/ui/pagination";

const PAGE_SIZE = 20;
const pageCount = Math.max(1, Math.ceil(filtered.length / PAGE_SIZE));
const current = Math.min(page, pageCount);
const rows = filtered.slice((current - 1) * PAGE_SIZE, current * PAGE_SIZE);

<Paginator page={current} pageCount={pageCount} onPageChange={setPage} size="sm" />
```

## Row actions and links

Put a menu in the last cell for per-row actions:

```tsx
<Cell>
  <MenuTrigger>
    <Button variant="ghost" size="icon-sm" aria-label={`Actions for ${inv.id}`}>
      <MoreHorizontalIcon />
    </Button>
    <MenuContent placement="bottom end">
      <MenuItem onAction={() => open(inv)}>View</MenuItem>
      <MenuItem onAction={() => download(inv)}>Download PDF</MenuItem>
      <MenuSeparator />
      <MenuItem variant="destructive" onAction={() => voidInvoice(inv)}>Void</MenuItem>
    </MenuContent>
  </MenuTrigger>
</Cell>
```

To make whole rows navigate, give `Row` an `href`. React Aria treats the row as a link
(Enter opens it, and with a [RouterProvider](/docs/routing) it uses your router):

```tsx
<Row href={`/invoices/${inv.id}`}>…</Row>
```

## Server-side data

For large data sets, keep the same state (`sort`, `query`, `page`) and fetch instead of
filtering in memory:

```tsx
const params = new URLSearchParams({
  q: query,
  sort: `${String(sort.column)}:${sort.direction}`,
  page: String(page),
});
const { data, isLoading } = useSWR(`/api/invoices?${params}`, fetcher);

<TableBody
  items={data?.rows ?? []}
  renderEmptyState={() => (isLoading ? <Spinner /> : "No invoices found.")}
>
  …
</TableBody>
```

Put the state in the URL (search params) when people should be able to share or
bookmark a filtered view.

## Responsive tables

Tables scroll horizontally inside their frame on small screens. For phone-first lists,
consider a [Grid List](/docs/components/grid-list) with stacked content instead of
squeezing columns.

---

# Overlays & focus management

Source: https://desyne.dev/docs/overlays

> Choose between Dialog, Sheet, Popover, Menu, Tooltip and Toast, open them from triggers or state, and keep focus where users expect it.

Overlays are where accessibility usually breaks: focus escapes, Escape doesn't work,
screen readers keep reading the page behind. Desyne's overlays are React Aria
overlays, so focus containment, restoration, dismissal and the right roles are handled.
Your job is choosing the right one.

## Which overlay?

| Use                                                 | When                                                                    | Blocks the page? |
| --------------------------------------------------- | ----------------------------------------------------------------------- | ---------------- |
| [Dialog](/docs/components/dialog)                   | A focused task or decision: edit a record, confirm a delete             | Yes (modal)      |
| [Sheet](/docs/components/sheet)                     | Secondary content or long forms at the edge: filters, cart, mobile nav  | Yes (modal)      |
| [Popover](/docs/components/popover)                 | Small, contextual controls next to their trigger                        | No               |
| [Menu](/docs/components/menu)                       | A list of actions or navigation from a button                           | No               |
| [Tooltip](/docs/components/tooltip)                 | A short label for an icon or truncated text. Never interactive content  | No               |
| [Toast](/docs/components/toast)                     | Feedback after something happened: saved, failed, undo                  | No               |
| [Command Palette](/docs/components/command-palette) | Searchable actions and navigation, usually on <kbd>⌘</kbd> <kbd>K</kbd> | Yes              |

## Triggers

Overlays open from a trigger wrapper that pairs a button with its overlay. The trigger
must be a pressable React Aria element such as Desyne's `Button`.

```tsx
<DialogTrigger>
  <Button variant="outline">Edit profile</Button>
  <DialogContent>
    {({ close }) => (
      <>
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>Update how your name appears to your team.</DialogDescription>
        </DialogHeader>
        <TextField label="Name" defaultValue="Ada Lovelace" autoFocus />
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <Button onPress={() => { save(); close(); }}>Save</Button>
        </DialogFooter>
      </>
    )}
  </DialogContent>
</DialogTrigger>
```

| Overlay | Trigger          | Content                     |
| ------- | ---------------- | --------------------------- |
| Dialog  | `DialogTrigger`  | `DialogContent`             |
| Sheet   | `SheetTrigger`   | `SheetContent`              |
| Popover | `PopoverTrigger` | `Popover` + `PopoverDialog` |
| Menu    | `MenuTrigger`    | `MenuContent`               |
| Tooltip | `TooltipTrigger` | `Tooltip`                   |

`DialogContent` and `SheetContent` children can be a function that receives `close`.
`DialogClose` is a Button with `slot="close"`, so any button inside closes the dialog.

## Opening from state

When something other than a button opens the overlay (a menu item, a keyboard
shortcut, a URL), control it with `isOpen` and `onOpenChange` and skip the trigger:

```tsx
const [renaming, setRenaming] = useState(false);

<MenuTrigger>
  <Button variant="ghost" size="icon" aria-label="Actions"><MoreHorizontalIcon /></Button>
  <MenuContent>
    <MenuItem onAction={() => setRenaming(true)}>Rename…</MenuItem>
  </MenuContent>
</MenuTrigger>

<DialogContent isOpen={renaming} onOpenChange={setRenaming} size="sm">
  …
</DialogContent>
```

Focus returns to the element that was focused before the dialog opened, here the menu
button.

## Focus behaviour

| Moment                          | What happens                                                                                 |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| Open                            | Focus moves into the overlay: the first focusable element, or the one with `autoFocus`       |
| While open (modal)              | <kbd>Tab</kbd> cycles inside; the page behind is hidden from screen readers and can't scroll |
| <kbd>Esc</kbd> or outside click | Closes, unless the dialog is `role="alertdialog"` or `isDismissable={false}`                 |
| Close                           | Focus returns to the trigger                                                                 |

Choose the starting point deliberately:

* **Forms:** `autoFocus` on the first field.
* **Destructive confirmations:** let focus land on the first button (Cancel), not on
  the destructive action.
* **Read-only content:** let focus go to the dialog itself; screen readers read the
  title.

## Confirmation dialogs

Use `role="alertdialog"` for decisions that interrupt. It can't be dismissed by clicking
outside, and screen readers announce it urgently.

```tsx
<DialogTrigger>
  <Button variant="outline" color="danger">Delete project</Button>
  <DialogContent role="alertdialog" size="sm">
    <div className="flex gap-4">
      <DialogIcon tone="danger"><TriangleAlertIcon /></DialogIcon>
      <div className="grid gap-1.5">
        <DialogTitle>Delete this project?</DialogTitle>
        <DialogDescription>All deployments and logs will be permanently removed.</DialogDescription>
      </div>
    </div>
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <DialogClose variant="solid" color="danger">Delete</DialogClose>
    </DialogFooter>
  </DialogContent>
</DialogTrigger>
```

Every dialog needs a title. If there's no visible `DialogTitle`, pass `aria-label` to
`DialogContent`.

## Sizes and sides

`DialogContent` takes `size`: `sm` (384px), `md` (512px, default), `lg` (672px), `xl`
(896px) or `full`. Content taller than the viewport scrolls inside the dialog; wrap long
content in `DialogBody` to keep the header and footer fixed.

`SheetContent` takes `side` (`right` by default, `left`, `top`, `bottom`) and `size`
(`sm`, `md`, `lg`).

## Popovers vs dialogs

A popover is non-modal: the page stays interactive and the popover closes when focus
leaves. Use it for quick settings that apply immediately. If the content has a submit
button, several fields or must not be lost by an outside click, use a Dialog.

## Tooltips

Tooltips appear on hover after a short delay and immediately on keyboard focus. They
never appear on touch, so don't put anything there that people need. Their content is
plain text: no links or buttons.

```tsx
<TooltipTrigger delay={300}>
  <Button variant="ghost" size="icon" aria-label="Duplicate"><CopyIcon /></Button>
  <Tooltip>Duplicate</Tooltip>
</TooltipTrigger>
```

## Toasts

Mount `<Toaster />` once in your root layout, then call `toast()` anywhere, including
outside React components:

```tsx title="app/layout.tsx"
import { Toaster } from "@/components/ui/toast";

<body>
  {children}
  <Toaster />
</body>
```

```tsx
import { toast } from "@/components/ui/toast";

toast.success("Invoice sent", { description: "INV-1042 to billing@acme.com" });
toast("Project archived", { action: { label: "Undo", onClick: restore } });
toast.promise(save(), { loading: "Saving…", success: "Saved", error: "Couldn't save" });
```

Don't use toasts for errors that need action (put those next to the field) or for
critical information: they disappear.

## Stacking overlays

Opening a dialog from a sheet, or a menu inside a dialog, works: each overlay contains
its own focus, and <kbd>Esc</kbd> closes only the top one. Avoid more than two levels;
use steps inside one dialog instead (see the wizard recipe on
[Dialog](/docs/components/dialog)).

---

# Routing integration

Source: https://desyne.dev/docs/routing

> Connect React Aria links to Next.js, React Router or TanStack Router with RouterProvider, so client-side navigation works everywhere.

Many components render links: `Link`, `Breadcrumb`, `Tab`, `MenuItem`, `ListBoxItem`,
`GridListItem`, `Row`, `Tag`, `SidebarMenuButton` and `PaginationLink` all accept an
`href`. By default React Aria renders a real `<a href>`, which works but does a full page
load. `RouterProvider` routes those clicks through your framework's router instead.

## Next.js (App Router)

```tsx title="app/providers.tsx"
"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

declare module "react-aria-components" {
  interface RouterConfig {
    routerOptions: NonNullable<Parameters<ReturnType<typeof useRouter>["push"]>[1]>;
  }
}

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}
```

```tsx title="app/layout.tsx"
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

The module augmentation is optional. It types `routerOptions`, which lets a single link
pass options to `router.push`:

```tsx
<Link href="/settings#billing" routerOptions={{ scroll: false }}>Billing</Link>
```

This is the setup the Pro site uses, alongside `next-themes` and the `Toaster`.

### Base paths

If your app runs under a `basePath`, pass `useHref` so rendered `href`s include it:

```tsx
const withBase = (href: string) => (href.startsWith("/") ? `/docs${href}` : href);

<RouterProvider navigate={(href) => router.push(href)} useHref={withBase}>
```

## React Router

```tsx title="src/root.tsx"
import { RouterProvider } from "react-aria-components";
import { type NavigateOptions, Outlet, useHref, useNavigate } from "react-router";

declare module "react-aria-components" {
  interface RouterConfig {
    routerOptions: NavigateOptions;
  }
}

export default function Root() {
  const navigate = useNavigate();
  return (
    <RouterProvider navigate={navigate} useHref={useHref}>
      <Outlet />
    </RouterProvider>
  );
}
```

`useHref` makes rendered links respect React Router's `basename`.

## TanStack Router

```tsx title="src/routes/__root.tsx"
import {
  type NavigateOptions,
  Outlet,
  type ToOptions,
  useRouter,
} from "@tanstack/react-router";
import { RouterProvider } from "react-aria-components";

declare module "react-aria-components" {
  interface RouterConfig {
    href: ToOptions["to"];
    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
  }
}

function Root() {
  const router = useRouter();
  return (
    <RouterProvider
      navigate={(to, options) => router.navigate({ ...options, to })}
      useHref={(to) => router.buildLocation({ to }).href}
    >
      <Outlet />
    </RouterProvider>
  );
}
```

## Active states

React Aria doesn't know the current route, so you mark the active item. For tabs,
derive the selected key from the path:

```tsx
"use client";

import { usePathname } from "next/navigation";
import { Tab, TabList, Tabs } from "@/components/ui/tabs";

export function SettingsTabs() {
  const pathname = usePathname();
  return (
    <Tabs selectedKey={pathname}>
      <TabList aria-label="Settings">
        <Tab id="/settings" href="/settings">General</Tab>
        <Tab id="/settings/billing" href="/settings/billing">Billing</Tab>
        <Tab id="/settings/members" href="/settings/members">Members</Tab>
      </TabList>
    </Tabs>
  );
}
```

For sidebars, pass `isActive={pathname === item.href}` to `SidebarMenuButton`, which
also sets `aria-current="page"`.

## When to keep plain links

Your framework's own `<Link>` (such as `next/link`) is still the right choice for content
links in prose and cards: it prefetches routes. Use React Aria links where the component
needs them (menus, tabs, rows, breadcrumbs), and `RouterProvider` makes those navigate
client-side too.

<Callout title="External links">
  `RouterProvider` only handles same-origin URLs. Links with a different origin, a
  `target="_blank"` or a modifier key (<kbd>⌘</kbd>-click) open natively.
</Callout>

---

# Server components

Source: https://desyne.dev/docs/server-components

> Which components are server-safe, how client components fit into the App Router, and patterns for passing data and actions across the boundary.

React Aria components rely on state, effects and event handlers, so almost every
Desyne component is a client component and starts with `"use client"`. You can still
render them from server components: the directive marks the boundary, and their props
are serialised from the server.

## Server-safe components

These render plain elements with no hooks and no `"use client"`, so they stay on the
server and add no JavaScript:

| Component                                 | Notes                                                   |
| ----------------------------------------- | ------------------------------------------------------- |
| [Badge](/docs/components/badge)           | Tones work on the server                                |
| [Card](/docs/components/card)             | All parts (`CardHeader`, `CardTitle`, `CardContent`, …) |
| [Item](/docs/components/item)             | List rows for settings and summaries                    |
| [Skeleton](/docs/components/skeleton)     | Pair with `loading.tsx`                                 |
| [Spinner](/docs/components/spinner)       |                                                         |
| [Empty](/docs/components/empty)           | Empty states                                            |
| [Typography](/docs/components/typography) | Headings, text and prose                                |

`lib/primitive.ts` has no React Aria import and no `"use client"`, so tones and
`composeTailwindRenderProps` can be used in server code too.

## Using client components from a server page

Import them directly. Pass serialisable props (strings, numbers, plain objects,
arrays, dates as strings):

```tsx title="app/settings/page.tsx"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Switch } from "@/components/ui/switch";
import { getPreferences } from "@/lib/data";

export default async function SettingsPage() {
  const prefs = await getPreferences(); // runs on the server

  return (
    <Card>
      <CardHeader>
        <CardTitle>Notifications</CardTitle>
      </CardHeader>
      <CardContent className="grid gap-4">
        <Switch defaultSelected={prefs.digest}>Weekly digest</Switch>
        <Switch defaultSelected={prefs.mentions}>Mentions</Switch>
      </CardContent>
    </Card>
  );
}
```

Uncontrolled props (`defaultSelected`, `defaultValue`) are the easy path: the server
supplies the initial value and the component manages the rest.

## Event handlers need a client component

Functions can't cross from server to client, so `onPress`, `onChange` and render
functions (`{(item) => …}`) must live in a client file. Wrap the interactive part:

```tsx title="app/settings/digest-switch.tsx"
"use client";

import { Switch } from "@/components/ui/switch";
import { toast } from "@/components/ui/toast";
import { setDigest } from "./actions";

export function DigestSwitch({ initial }: { initial: boolean }) {
  return (
    <Switch
      defaultSelected={initial}
      onChange={async (on) => {
        await setDigest(on);
        toast.success(on ? "Digest on" : "Digest off");
      }}
    >
      Weekly digest
    </Switch>
  );
}
```

```ts title="app/settings/actions.ts"
"use server";

export async function setDigest(enabled: boolean) {
  // await db.preferences.update({ digest: enabled })
}
```

Server actions are the exception to "no functions": they can be passed as props or
imported into client components. See [Forms](/docs/forms#with-zod) for
`useActionState` with validation.

## Collections with render functions

Dynamic collections take a render function, which is a client concern. Keep the data
fetching on the server and the rendering in a small client component:

```tsx title="app/team/page.tsx"
import { MemberTable } from "./member-table";

export default async function TeamPage() {
  const members = await db.members.list(); // [{ id, name, role }]
  return <MemberTable members={members} />;
}
```

```tsx title="app/team/member-table.tsx"
"use client";

import { Cell, Column, Row, Table, TableBody, TableHeader } from "@/components/ui/table";

type Member = { id: string; name: string; role: string };

export function MemberTable({ members }: { members: Member[] }) {
  return (
    <Table aria-label="Team members">
      <TableHeader>
        <Column isRowHeader>Name</Column>
        <Column>Role</Column>
      </TableHeader>
      <TableBody items={members}>
        {(m) => (
          <Row>
            <Cell>{m.name}</Cell>
            <Cell>{m.role}</Cell>
          </Row>
        )}
      </TableBody>
    </Table>
  );
}
```

Static collections, where children are written out as JSX, can be rendered from a
server component:

```tsx
<Select label="Region" name="region" defaultSelectedKey="eu">
  <SelectItem id="eu">Europe</SelectItem>
  <SelectItem id="us">United States</SelectItem>
</Select>
```

## Providers

`RouterProvider`, `I18nProvider` and `next-themes` are client components. Put them in a
single `app/providers.tsx` with `"use client"` and render it from your root layout; the
pages inside remain server components. See [Routing](/docs/routing) and
[Dark mode](/docs/dark-mode).

## Loading states

Use server-safe Skeletons in `loading.tsx` so the placeholder streams before any
JavaScript loads:

```tsx title="app/team/loading.tsx"
import { Skeleton } from "@/components/ui/skeleton";

export default function Loading() {
  return (
    <div className="grid gap-2">
      {Array.from({ length: 6 }, (_, i) => (
        <Skeleton key={i} className="h-10 w-full" />
      ))}
    </div>
  );
}
```

---

# What's in Pro

Source: https://desyne.dev/docs/pro

> Desyne Pro adds production-ready blocks and complete multi-page templates, built from the same open components.

The component library is free. **Desyne Pro** is the layer above it: finished
sections and whole products, written with the same components, tokens and conventions,
so they inherit your theme and read like code you wrote.

<Cards>
  <Card title="Installing blocks" href="/docs/pro/blocks" description="Add any block with the shadcn CLI and your license key." />

  <Card title="Using templates" href="/docs/pro/templates" description="Download a complete Next.js project and make it yours." />

  <Card title="Licensing & seats" href="/docs/pro/licensing" description="Keys, accounts, Team seats and what the license allows." />

  <Card title="Pro FAQ" href="/docs/pro/faq" description="Payments, updates, refunds and support." />
</Cards>

## Blocks

Blocks are sections and screens: a pricing table, a dashboard, a checkout, a chat
interface. Each one is a `.tsx` file (sometimes with helpers beside it) that you install
by name. They're grouped into seven categories:

| Category    | Examples                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------- |
| Marketing   | Heroes, feature grids, pricing, testimonials, logo clouds, FAQs, CTAs, footers                |
| Application | Sign-in and onboarding, app shells, dashboards, settings, tables, empty states, notifications |
| Commerce    | Product grids and pages, bags, checkout, order history, reviews                               |
| Charts      | Area, bar, line, radial, Sankey and sunburst charts as cards and open layouts                 |
| UI kits     | Pagination, toggle groups, selects, calendars, codes and other composed patterns              |
| Pages       | Complete about, careers, contact, pricing, blog and changelog pages                           |
| AI          | Chat, prompt inputs, assistants, agents, image and voice interfaces                           |

Every block has realistic content, light and dark themes and responsive layouts, and is
checked at phone, tablet and desktop widths. Previews are public; the source and CLI
install need a license, except for a few free teasers.

## Templates

Templates are complete Next.js projects with several pages each, shipped as a zip:

| Template  | What it is                            | Type           |
| --------- | ------------------------------------- | -------------- |
| Veyra     | Marketing site for a support platform | Marketing site |
| Routely   | Delivery software marketing site      | Marketing site |
| Wrenly    | Product analytics SaaS app            | SaaS app       |
| Chairside | Dental clinic admin app               | SaaS app       |
| Sayso     | AI assistant builder app              | SaaS app       |
| Tandem    | Project management app                | SaaS app       |
| Finch     | Personal finance dashboard            | SaaS app       |
| Brisk     | CRM and sales app                     | SaaS app       |
| Northfold | Storefront for an everyday gear brand | Storefront     |
| Kestrel   | Site for an independent design studio | Agency site    |
| Halden    | Branding and packaging studio         | Agency site    |
| Tessera   | Commercial real estate brokerage      | Real estate    |
| Pearl     | Dental clinic website                 | Healthcare     |
| Dispatch  | News and magazine publication         | Publication    |
| Ines      | Personal portfolio for a designer     | Portfolio      |
| Strata    | Developer documentation site          | Documentation  |
| Olea      | Restaurant and bakery website         | Restaurant     |
| Wayfare   | Hotel and travel booking site         | Travel         |
| Meridian  | Online course platform                | Education      |
| Overture  | Conference and event site             | Event          |

Each one has a live demo on the Pro site. App templates are interactive (navigation,
filters, dialogs, forms), and site templates include subtle Motion animations that
respect reduced motion.

## Plans

|                                | Free          | Pro           | Team          |
| ------------------------------ | ------------- | ------------- | ------------- |
| Price                          | $0            | $149 one-time | $399 one-time |
| Developers                     | Unlimited     | 1             | Up to 10      |
| Core components                | ✓             | ✓             | ✓             |
| Blocks                         | A few teasers | All           | All           |
| Templates                      | —             | All           | All           |
| CLI install of blocks          | Teasers only  | ✓             | ✓             |
| Future blocks and templates    | —             | ✓             | ✓             |
| Commercial and client projects | ✓             | ✓             | ✓             |
| Priority support               | —             | —             | ✓             |

There's no subscription: you pay once and keep access, including to what's added later.

---

# Installing blocks

Source: https://desyne.dev/docs/pro/blocks

> Browse blocks, connect the private registry with your license key, install with the shadcn CLI, and customise what lands in your project.

## 1. Find a block

Browse by category and group on the Pro site's **Blocks** page. Each block opens in a
viewer with:

* a live preview you can switch between light and dark and resize to phone, tablet and
  desktop widths,
* the source, file by file (with a license, or for free teasers),
* its install command, for example `npx shadcn@latest add @desyne-pro/pricing-02`.

## 2. Connect the registry (once per project)

Get your key from the **Account** page on the Pro site, then:

```bash title=".env.local"
DESYNE_PRO_LICENSE=dsp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```json title="components.json"
{
  "registries": {
    "@desyne": "https://desyne.dev/r/{name}.json",
    "@desyne-pro": {
      "url": "https://pro.desyne.dev/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${DESYNE_PRO_LICENSE}"
      }
    }
  }
}
```

The Account page shows these snippets with your real registry URL and a copy button.
Keep both registries: Pro blocks depend on components from `@desyne`.

## 3. Install

```bash
npx shadcn@latest add @desyne-pro/pricing-02
```

```txt
✓ Checking registry
✓ Installing dependencies
✓ Created files
  - components/blocks/pricing-02/pricing-02.tsx
```

The CLI also installs every component the block imports (`button`, `card`, `badge`,
…) from `@desyne`, and npm packages it uses (`lucide-react`, sometimes
`recharts` or `motion`). Components you already have are left alone unless you pass
`--overwrite`.

## 4. Use it

Each block's main file has a default export:

```tsx title="app/pricing/page.tsx"
import Pricing from "@/components/blocks/pricing-02/pricing-02";

export default function PricingPage() {
  return <Pricing />;
}
```

Blocks are client components (`"use client"`) when they're interactive, so they render
from server pages without changes.

## Customising

Blocks are starting points, not black boxes:

* **Content** is inline: headings, prices, table rows and chart data are plain
  constants at the top of the file or in the JSX. Replace them with your copy or props.
* **Styling** uses your tokens. Change `--brand` or `--radius` and every block follows.
* **Structure** is ordinary JSX. Delete sections, reorder columns, swap a component.
* **Data**: turn constants into props and pass real data from a server component.

```tsx
// Before: data inside the block
const plans = [{ name: "Starter", price: 12 }, /* … */];

// After: the block takes data as a prop
export default function Pricing({ plans }: { plans: Plan[] }) { /* … */ }
```

## In CI and teams

* Add `DESYNE_PRO_LICENSE` as a CI secret only if your pipeline runs the CLI. Installed
  block files are committed to your repo, so builds don't need the key.
* On a Team license, each teammate can use their own personal key (see
  [Licensing](/docs/pro/licensing#team-seats)), so removing someone doesn't break
  everyone else's setup.

## Troubleshooting

| Problem                                           | Fix                                                                                                                                                                                       |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` / "A valid Desyne Pro license is required." | The key isn't reaching the CLI. Check `echo $DESYNE_PRO_LICENSE` or the `.env.local` file in the directory where you run the command, and that the license is active on your account page |
| `404`                                             | Check the block name in its viewer; names look like `hero-01`, `dashboard-01`                                                                                                             |
| Imports of `@/components/ui/*` fail               | Your `components.json` aliases differ. Re-run `npx shadcn@latest init` or fix the paths in the block                                                                                      |
| Styles look unstyled                              | Make sure Tailwind scans `components/blocks` (it does by default in Tailwind v4 unless you've restricted `@source`)                                                                       |

---

# Using templates

Source: https://desyne.dev/docs/pro/templates

> Download a Pro template as a standalone Next.js project, run it, rebrand it, and replace the content.

Templates are complete products: a marketing site, a SaaS app, a storefront. Each one
is a standalone Next.js project that includes every Desyne component it uses, so it
runs without the registry or this repo.

## Download

1. Open a template on the Pro site's **Templates** page and try the live demo.
2. Sign in (or unlock with your key), then press **Download**. You get
   `<name>-template.zip`.

```bash
unzip veyra-template.zip && cd veyra-template
npm install        # or pnpm / bun
npm run dev        # http://localhost:3000
```

## What's inside

```txt
veyra-template/
  app/                 Next.js routes; each page is a thin wrapper around a screen
    layout.tsx         Fonts, theme provider, toaster
    theme.css          Design tokens (shadcn names). Rebrand here
    base.css           Base layer
  src/
    screens/           One component per page. Edit these to change a page
    components/        Sections and layout pieces (header, footer, hero, …)
    content.ts         Posts, changelog entries, products, customers…
    lib/link.tsx       Link helper (see below)
  components/ui/       The Desyne components this template uses
  lib/                 utils.ts and primitive.ts
  package.json         Only the dependencies the template needs
```

The `package.json` is generated from what the template imports: React, Next.js,
Tailwind v4, React Aria and whatever else it actually uses (for example `motion`,
`recharts`, `next-themes`).

## Make it yours

<Steps>
  <Step>
    ### Rebrand

    Edit `app/theme.css`: `--brand`, `--primary`, `--radius` and the neutrals. See
    [Theming](/docs/theming). Swap the logo component in `src/components` and the font in
    `app/layout.tsx`.
  </Step>

  <Step>
    ### Replace content

    Copy lives in the screens and sections, and repeated content (posts, products, plans,
    team) lives in `src/content.ts`. Replace it there or load it from your CMS or database.
  </Step>

  <Step>
    ### Remove what you don't need

    Delete a route folder in `app/` and its screen in `src/screens/`, and remove the nav
    entry from the header.
  </Step>

  <Step>
    ### Ship

    It's a normal Next.js app: `npm run build` and deploy anywhere Next.js runs.
  </Step>
</Steps>

## The link helper

`src/lib/link.tsx` lets the same pages run standalone and inside the Pro site's live demo
(which mounts them under a sub-path). In your project the base path is empty, so it
behaves like `next/link`. You can keep it, or replace `Link` imports with `next/link`
and `useNavigate()` with `useRouter().push`.

It also includes a `RouterBridge` that connects React Aria links to the Next.js router.
See [Routing](/docs/routing).

## Motion

Site templates animate with [Motion](https://motion.dev). The primitives live in
`src/components/motion.tsx` (`Reveal`, `Stagger`/`Item`, `Words`, `CountUp`, `Float`)
under a `MotionConfig` with `reducedMotion="user"`, so they respect the visitor's
setting. Remove the wrappers if you prefer a static site.

## Updating

Templates are a starting point; once downloaded, they're your code. New versions of a
template appear on the Pro site, and the [Changelog](/changelog) lists what changed. To
pick up a fix, download the new zip and diff it against your project.

## License

Templates are covered by your Pro or Team license: use them for unlimited client and
commercial projects, but don't resell them as templates or publish their source.

---

# Licensing & seats

Source: https://desyne.dev/docs/pro/licensing

> How purchases become license keys, how to sign in, regenerate keys and invite teammates, and what the license allows.

## How a purchase works

1. Choose **Pro** or **Team** on the pricing page. Checkout opens in a secure Paddle
   window; Paddle is our merchant of record and handles payment, sales tax and VAT, and
   your receipt. If you're signed in, your email is prefilled and the purchase is linked
   to your account straight away.
2. After payment you land on your **Account** page. It refreshes for a few seconds
   while the order is confirmed, then shows your license.
3. Each license has a key: `dsp_` followed by 32 characters.

Not signed in when you bought? Sign in later with the same email address. Licenses are
attached to accounts by verified email, so the purchase appears automatically.

## Signing in

The Pro site uses passwordless sign-in:

* **Email link.** Enter your email and click the link we send.
* **GitHub**, where enabled. Accounts with the same verified email are linked.

Signed in with an active license, you can see every block's source and download
templates in the browser without entering a key.

## Your key

The Account page shows your key masked, with buttons to reveal and copy it, and
ready-to-copy snippets for `components.json`, `.env.local` and a first install
command.

| Where the key is used        | How                                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
| shadcn CLI                   | `Authorization: Bearer ${DESYNE_PRO_LICENSE}` header in `components.json` ([setup](/docs/pro/blocks)) |
| A browser without signing in | **Unlock Pro** dialog → "use a license key". Stored in a secure, HTTP-only cookie for that browser    |
| CI                           | A `DESYNE_PRO_LICENSE` secret, only if the pipeline runs the CLI                                      |

Treat the key like a password: keep it in `.env` files and CI secrets, never in code you
commit.

### Regenerating

If a key leaks, press **Regenerate key** on the Account page. The old key stops working
immediately, everywhere: update `.env.local` files and CI secrets with the new one.
Teammates' personal keys on a Team license keep working.

## Team seats

A Team license has **10 seats**, and the owner uses one.

* **Invite** a teammate by email from the Account page. They get access as soon as they
  sign in with that (verified) email address.
* Each member gets a **personal key**, shown on their own Account page, for their CLI
  setup. They don't need the owner's key.
* **Remove** a member to free the seat. Their personal key stops working immediately.
* When all seats are in use, remove someone before inviting another person.

Pro licenses are for one developer and don't have seats; upgrade to Team to share
access.

## Refunds

Refunds are handled by Paddle, our merchant of record. A full refund deactivates the
license and every member key on it; the account page then shows the license as
inactive. A partial refund leaves the license active.

## What the license allows

| You can                                                                  | You can't                                                                  |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Use the free components in any project, personal or commercial           | Resell or redistribute Pro blocks or templates as a kit, theme or template |
| Use Pro blocks and templates in unlimited client and commercial projects | Publish Pro source in a public repository                                  |
| Modify everything, and ship it inside apps you sell                      | Share a personal (Pro) license with your team                              |
| Keep using everything you downloaded, forever                            |                                                                            |

Read the full terms on the [About & license](/about#license) page.

---

# Pro FAQ

Source: https://desyne.dev/docs/pro/faq

> Common questions about buying, installing and using Desyne Pro.

### Is it really a one-time payment?

Yes. Pay once and keep access to every block and template, including the ones added
later. There's no subscription.

### Who processes the payment?

[Paddle](https://www.paddle.com) is our merchant of record. It handles the checkout,
sales tax and VAT, invoices and receipts, and refunds. Your receipt comes from Paddle.

### Do I need Pro to use the components?

No. Every component in these docs is free for any project. Pro adds blocks and
templates built from them.

### Can I use Pro in client and commercial projects?

Yes, in unlimited projects. You can't resell the blocks or templates as a kit, theme or
template, or publish their source in a public repository.

### Which stack do I need?

React 19 and Tailwind CSS v4. Blocks run in Next.js, Vite, React Router or TanStack
Start. Templates ship as Next.js projects.

### How do I install a block?

Add the Pro registry and your license key to `components.json`, then run the add
command shown on the block. See [Installing blocks](/docs/pro/blocks).

### Does my build need the license key?

No. Installed blocks are files in your repository. The key is only needed when the
shadcn CLI downloads a block.

### How does the Team license work?

Up to ten developers. The owner invites teammates by email, and each teammate gets their
own key. See [Team seats](/docs/pro/licensing#team-seats).

### My key stopped working.

Someone may have regenerated it, or the license was refunded. Check the Account page:
it shows the current key and the license status.

### Do blocks work with my existing shadcn/ui components?

Yes. Blocks import components from `@/components/ui/*` using shadcn token names. When a
block needs a Desyne component you don't have, the CLI installs it. If you already
have a shadcn component with the same file name, the CLI asks before replacing it.

### How do I get support?

Reply to your receipt email. Team licenses get priority support.

---

# AI & llms.txt

Source: https://desyne.dev/docs/ai

> Give Cursor, Claude, ChatGPT or any coding assistant accurate Desyne context with llms.txt, full-text Markdown and per-page Markdown.

Coding assistants guess at APIs they haven't seen. Desyne publishes its docs in
plain Markdown so you can give them the real thing: component props, examples and
patterns from this site, not from their training data.

## What's available

| URL                                | What it is                                                                                               | Use it when                          |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| [`/llms.txt`](/llms.txt)           | An index of every page with a one-line description, following the [llms.txt](https://llmstxt.org) format | The tool can follow links itself     |
| [`/llms-full.txt`](/llms-full.txt) | Every docs page concatenated as Markdown                                                                 | You want everything in one context   |
| `/docs/<page>.md`                  | A single page as Markdown, e.g. [`/docs/forms.md`](/docs/forms.md)                                       | You only need one component or guide |

Docs pages also return Markdown when a client asks for it with an
`Accept: text/markdown` header, so agents that request Markdown get it from the normal
URL.

## Copy a page

Every docs page has a **Copy Markdown** button under the title. It copies the page as
Markdown, ready to paste into a chat. The menu next to it opens the page directly in
ChatGPT, Claude, Cursor or Scira AI with the Markdown URL attached.

## Cursor

Add the docs once and reference them in any chat:

1. **Settings → Indexing & Docs → Add doc**, and enter the `/llms-full.txt` URL of this
   site.
2. In chat, type `@Docs` and pick it.

Or add a project rule so every request uses Desyne conventions:

```md title=".cursor/rules/desyne.mdc"
---
description: UI components
globs: ["**/*.tsx"]
---
UI components come from Desyne (React Aria + shadcn tokens), installed in components/ui.
- Use onPress, not onClick, on Button. Use isDisabled, isRequired, isInvalid.
- Fields take label, description and errorMessage props. Wrap forms in react-aria-components <Form>.
- Colors via the `color` prop (primary, brand, neutral, danger, success, warning, info).
- Style states with data-* variants: data-hovered:, data-pressed:, data-focus-visible:, data-selected:.
- Reference: https://desyne.dev/llms.txt
```

## Claude

* **Claude Code:** add a line to `CLAUDE.md` such as
  "UI docs: fetch [https://desyne.dev/llms.txt](https://desyne.dev/llms.txt) and the linked `.md` pages before
  writing components." Claude Code can fetch the index and the pages it needs.
* **Claude.ai projects:** download `/llms-full.txt` and add it to the project's
  knowledge, or paste single pages with **Copy Markdown**.

## ChatGPT and other chat tools

Paste the output of **Copy Markdown** for the components you're working with, or attach
`llms-full.txt` as a file. For a single question, linking the `.md` URL of the page is
often enough for tools that browse.

## The shadcn MCP server

The shadcn CLI includes an MCP server that lets assistants browse and install from the
registries in your `components.json`, including `@desyne` and (with your key)
`@desyne-pro`:

```bash
npx shadcn@latest mcp init --client claude   # or cursor, vscode
```

Then ask things like "add the date picker from @desyne" or "show me Pro pricing
blocks".

## Prompting tips

* **Name the library and version of React Aria patterns:** "Use Desyne's `Select`
  (React Aria) with `selectedKey`/`onSelectionChange`."
* **Point at an example:** "Follow the data table recipe on /docs/components/table.md."
* **Ask for accessible names:** "Every icon-only button needs `aria-label`."
* **Keep the tokens:** "Use semantic colors (`bg-card`, `text-muted-foreground`), not
  raw palette colors."

---

# Contributing

Source: https://desyne.dev/docs/contributing

> Run the repo locally, add a component with examples and docs, and the conventions a pull request should follow.

Desyne is a Bun and Turborepo monorepo.

| Path            | What it is                                                                                                                                      |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/ui`   | The components (`src/components/ui`), `lib/utils.ts`, `lib/primitive.ts`, `theme.css`, `base.css` and the registry metadata (`src/registry.ts`) |
| `apps/docs`     | This site (Next.js + Fumadocs). Also serves the public registry at `/r/*.json`                                                                  |
| `apps/pro`      | The Pro site: blocks, templates, accounts and the private registry                                                                              |
| `templates/*`   | Pro template sources                                                                                                                            |
| `registry.json` | Generated shadcn registry manifest                                                                                                              |

## Run it

```bash
bun install
bun run dev              # docs on :3000 (and templates)
bun run registry:build   # registry.json → apps/docs/public/r
bun run typecheck
bun run lint             # Biome
bun run format           # Biome, writing fixes
```

## Add a component

<Steps>
  <Step>
    ### Write it

    Create `packages/ui/src/components/ui/<name>.tsx`. Import from `@/lib/utils`,
    `@/lib/primitive` and `@/components/ui/*`, the same paths it will have in a user's
    project. Build on a React Aria primitive, style states with `data-*` variants and use
    `tailwind-variants` for variants and sizes.
  </Step>

  <Step>
    ### Register it

    Add an entry to `components` in `packages/ui/src/registry.ts` with `title`,
    `description` and `category`. Dependencies are inferred from the imports when the
    registry builds.
  </Step>

  <Step>
    ### Add examples

    Create `apps/docs/examples/<name>/demo.tsx` plus one file per example. Each file
    default-exports a component and becomes a Preview/Code block. Recipes (`recipe-*.tsx`)
    combine several components into a realistic pattern.
  </Step>

  <Step>
    ### Document it

    Add `apps/docs/content/docs/components/<name>.mdx` and list it in
    `components/meta.json`. Use the standard structure: `<ComponentLinks>`,
    `<ComponentPreview name="<name>/demo" />`, ````bash
npx shadcn@latest add @desyne/<name>
````, Usage,
    Examples, Accessibility and API Reference (`<TypeTable>`). The gallery picks it up
    automatically.
  </Step>
</Steps>

## Conventions

* **Tokens:** shadcn names only. New tokens need a light and a dark value and a
  `cssVars` entry so the CLI can add them.
* **Sizes:** controls use the 28 / 32 / 40px scale (`sm`, `md`, `lg`).
* **Colors:** components with a color take `color` and use `tones` from
  `lib/primitive.ts`.
* **Fields:** text-like controls use `fieldVariants` from `field.tsx`.
* **Accessibility:** keyboard and screen reader behaviour must match the React Aria
  pattern. Test with the keyboard and one screen reader before opening a PR.
* **Reduced motion:** continuous animation needs a `motion-reduce:` fallback.
* **Server safety:** only add `"use client"` when the component needs it.

## Generated files

Don't edit these by hand; their scripts overwrite them:

* `registry.json` (from `scripts/build-registry.ts`)
* `apps/docs/examples/__index__.tsx` (from `apps/docs/scripts/build-examples.ts`, run on dev and build)
* `apps/pro/generated/` (from `bun run blocks` and `bun run templates`)

## Docs pages

Guides live in `apps/docs/content/docs/*.mdx` and are ordered in `meta.json`. MDX
pages can use `Callout`, `Cards`, `Tabs`, `Steps`, `TypeTable` and `ComponentPreview`.
Keep paragraphs short, show code that compiles against the real components, and link
to related pages.

---

# License

Source: https://desyne.dev/docs/license

> What you can do with the free components and with Pro blocks and templates, in plain words.

## Free components

Every component in these docs is free to use in any project, personal or commercial.
Once installed, the source is yours: modify it, ship it in products you sell, keep it
forever.

## Pro blocks and templates

A Pro or Team license lets you:

* Use Pro blocks and templates in unlimited client and commercial projects.
* Modify everything, and ship it inside apps and sites you sell.
* Keep using everything you downloaded, forever.

You can't:

* Resell or redistribute Pro blocks or templates as a kit, theme or template.
* Publish Pro source in a public repository.
* Share a personal (Pro) license with your team. That's what Team is for.

A Pro license covers one developer; Team covers up to ten. See
[Licensing & seats](/docs/pro/licensing) for keys and team management.

## Third-party code

Components build on open-source packages, each under its own license:
[React Aria Components](https://github.com/adobe/react-spectrum) (Apache 2.0),
[Tailwind CSS](https://github.com/tailwindlabs/tailwindcss) (MIT),
[tailwind-variants](https://github.com/heroui-inc/tailwind-variants) (MIT),
[Lucide](https://github.com/lucide-icons/lucide) (ISC) and, for specific components,
[Sonner](https://github.com/emilkowalski/sonner), [Recharts](https://github.com/recharts/recharts),
[Embla Carousel](https://github.com/davidjerleke/embla-carousel) and
[input-otp](https://github.com/guilhermerodz/input-otp) (all MIT).

The full terms are on the
[About & license](/about#license) page.

---

# Components

Source: https://desyne.dev/docs/components

> Every component, grouped by category. Click one for examples, code and install instructions.



---

# Typography

Source: https://desyne.dev/docs/components/typography

> A small type system on the theme's tokens. Heading separates the semantic level from the visual size, Text covers body copy in sizes, tones and weights, and Prose styles raw HTML or MDX with no plugin.

```tsx title="typography/demo.tsx"
import { Code, Heading, Lead, Small, Text } from "@/components/ui/typography";

export default function TypographyDemo() {
  return (
    <article className="flex w-full max-w-xl flex-col gap-4">
      <Small className="font-medium text-brand uppercase tracking-wider">
        Engineering
      </Small>
      <Heading level={1}>Shipping a design system people actually use</Heading>
      <Lead>
        Components are the easy part. Adoption comes from docs, defaults and a
        migration path that respects the code teams already have.
      </Lead>
      <Text tone="subtle">
        We started by auditing every button in the product and found 41
        variations. Six months later there are three, all imported from{" "}
        <Code>@/components/ui/button</Code>, and nobody had to stop shipping to
        get there.
      </Text>
      <Small>Maya Chen · 6 min read · Updated March 12</Small>
    </article>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/typography
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import {
  Blockquote,
  Code,
  Heading,
  Lead,
  List,
  Prose,
  Small,
  Text,
} from "@/components/ui/typography";
```

```tsx
<Heading level={1}>Billing</Heading>
<Lead>Plans, invoices and payment methods for your workspace.</Lead>
<Text tone="muted">Changes apply at the start of the next billing cycle.</Text>
```

None of these are client components, so they render in server components with no JavaScript.

### When to use

* `Heading` — every title in an app screen or page. Pick `level` for the document outline and `size` for the look.
* `Text`, `Lead`, `Small`, `Code` — body copy you write in JSX, where you want the scale and tones without repeating class strings.
* `Prose` — content you don't write as JSX: MDX, Markdown rendered to HTML, CMS rich text, release notes from an API. It styles plain `<h2>`, `<p>`, `<ul>` and friends.
* Inside components such as [Card](/docs/components/card) or [Dialog](/docs/components/dialog), use their own title and description parts; they already follow this scale.

## Anatomy

| Part         | Renders         | Notes                                                                                                    |
| ------------ | --------------- | -------------------------------------------------------------------------------------------------------- |
| `Heading`    | `<h1>`–`<h6>`   | `level` picks the element (default 2). `size` picks the style; without it each level has a default size. |
| `Text`       | `<p>`           | `as` switches to `span`, `div`, `strong`, `em` or `small`. Sizes `xs`–`lg`, six tones, four weights.     |
| `Lead`       | `<p>`           | Larger, muted intro paragraph under a page title.                                                        |
| `Small`      | `<small>`       | Fine print: legal lines, timestamps, footnotes.                                                          |
| `Code`       | `<code>`        | Inline code. Sized in `em`, so it matches the surrounding text.                                          |
| `Blockquote` | `<blockquote>`  | With `attribution`, wrapped in `<figure>` with a `<figcaption>`.                                         |
| `List`       | `<ul>` / `<ol>` | `ordered` for numbers. Put `<li>` elements inside.                                                       |
| `Prose`      | `<div>`         | Styles the HTML elements inside it with descendant selectors.                                            |

## The scale

| Size      | Font size / line height     | Default for | Typical use                  |
| --------- | --------------------------- | ----------- | ---------------------------- |
| `display` | 36px → 48px from `sm`, 1.05 |             | Hero titles, big numbers     |
| `xl`      | 30px → 36px from `sm`, 1.25 | `h1`        | Page titles                  |
| `lg`      | 24px, 1.375                 | `h2`        | Section titles               |
| `md`      | 20px, 1.375                 | `h3`        | Card and subsection titles   |
| `sm`      | 18px, 1.375                 | `h4`        | Small groups, sidebars       |
| `xs`      | 16px, 1.5                   | `h5`, `h6`  | Inline headings, list titles |

Body text runs `xs` 12/20, `sm` 14/24, `md` 16/28 (default) and `lg` 18/32. Headings are `font-semibold` with tighter tracking from `md` up; all sizes are standard Tailwind steps, so they follow your theme's `--text-*` values if you've changed them.

Example `typography/scale`: source in https://desyne.dev/docs/components/typography.md

## Examples

### Level and size

The outline and the look are separate decisions. A settings card might hold an `h2` that should look small; a stat might be an `h3` that should look huge. Set `level` for screen readers and the page outline, `size` for the eye. Don't skip levels to get a smaller heading.

Example `typography/levels`: source in https://desyne.dev/docs/components/typography.md

### Text sizes and tones

`tone` sets the color from the theme: `default` for primary reading, `subtle` for softer body copy, `muted` for captions and helper text, plus `brand`, `danger` and `success`. `default`, `subtle` and `muted` all meet WCAG AA contrast for body text in light and dark mode.

Example `typography/text`: source in https://desyne.dev/docs/components/typography.md

### Inline elements

`Code` for identifiers, file names and commands; `Small` for fine print; `Text as="strong"` or `as="span"` for emphasis inside other text.

Example `typography/inline`: source in https://desyne.dev/docs/components/typography.md

### Lists and quotes

`List` keeps native list semantics and uses muted markers. `marker="none"` removes the bullets but keeps it announced as a list. `Blockquote` with `attribution` becomes a `<figure>` with a caption, the recommended markup for a quote with a source.

Example `typography/quote-and-list`: source in https://desyne.dev/docs/components/typography.md

### Prose

Wrap rendered HTML or MDX in `Prose`. It styles headings (`h1`–`h4`), paragraphs, links, bold text, lists (nested too), inline code, code blocks, blockquotes, horizontal rules, tables, images, figures and `kbd`. The first and last child lose their outer margin so the article sits flush in its container. Cap the line length with `max-w-prose` (65 characters).

Example `typography/prose`: source in https://desyne.dev/docs/components/typography.md

### Prose sizes

`size` sets the base font size; every margin and heading inside is in `em`, so the whole article scales together. Use `sm` in side panels and comments, `lg` for long-form reading.

Example `typography/prose-sizes`: source in https://desyne.dev/docs/components/typography.md

### With MDX

Pass `Prose` as the wrapper for your MDX content:

```tsx title="app/blog/[slug]/page.tsx"
import { Prose } from "@/components/ui/typography";

export default async function Post({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const { default: Content, title } = await import(`@/content/${slug}.mdx`);
  return (
    <Prose className="mx-auto max-w-prose">
      <Content />
    </Prose>
  );
}
```

For HTML from a CMS, sanitize it first and render it with `dangerouslySetInnerHTML` on the `Prose` element. To drop a styled component into an article (a [Card](/docs/components/card), a chart) without the article styles reaching it, close `Prose` before it and open a new one after.

## Guidance

* **One `h1` per page**, then `h2` for sections and `h3` inside them. Use `size` to adjust looks, never the level.
* **Keep lines short.** 45–75 characters reads best: `max-w-prose` on articles, `max-w-xl` or `max-w-2xl` on intros.
* **Use tone for hierarchy before size.** A muted line under a title usually reads better than a smaller font.
* **Don't put long text in color.** `brand`, `danger` and `success` are for short emphasis; pair them with an icon or wording so color isn't the only cue.
* **Balance and pretty.** Headings use `text-wrap: balance` and body text `text-wrap: pretty` to avoid lonely last words.
* **Numbers line up** with `tabular-nums` in tables and stats.

## Accessibility

* `Heading` always renders a real heading element, so screen reader users can jump between headings and the outline matches what they see.
* `List` keeps list semantics; with `marker="none"` it adds `role="list"` because Safari otherwise stops announcing unstyled lists.
* `Blockquote` with `attribution` uses `<figure>` and `<figcaption>` so the source is associated with the quote.
* Links inside `Prose` are underlined, not only colored.
* Text sizes are in `rem` and `em`, so they follow the user's browser font size setting.

## Styling

### Data slots

| Slot                     | Element                                              |
| ------------------------ | ---------------------------------------------------- |
| `data-slot="heading"`    | `Heading`                                            |
| `data-slot="text"`       | `Text`                                               |
| `data-slot="lead"`       | `Lead`                                               |
| `data-slot="small"`      | `Small`                                              |
| `data-slot="code"`       | `Code`                                               |
| `data-slot="blockquote"` | `Blockquote` (the `<figure>` is `blockquote-figure`) |
| `data-slot="list"`       | `List`                                               |
| `data-slot="prose"`      | `Prose`                                              |

### Reusing the styles

`headingVariants`, `textVariants` and `proseVariants` are exported, so you can apply the scale to other elements:

```tsx
import { headingVariants, textVariants } from "@/components/ui/typography";

<Link className={headingVariants({ size: "sm" })} href="/changelog">Changelog</Link>
<label className={textVariants({ size: "sm", tone: "muted" })}>Optional</label>
```

To change a Prose rule, edit the matching line in `proseVariants` (they're grouped by element), or add a descendant class at the call site: `<Prose className="[&_a]:no-underline">`.

## API Reference

### Heading

<TypeTable
  type="{
  level: { type: &#x22;1 | 2 | 3 | 4 | 5 | 6&#x22;, default: &#x22;2&#x22;, description: &#x22;Renders h1–h6.&#x22; },
  size: { type: '&#x22;display&#x22; | &#x22;xl&#x22; | &#x22;lg&#x22; | &#x22;md&#x22; | &#x22;sm&#x22; | &#x22;xs&#x22;', description: &#x22;Visual size. Defaults to xl for h1, lg for h2, md for h3, sm for h4 and xs for h5/h6.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

### Text

<TypeTable
  type="{
  as: { type: '&#x22;p&#x22; | &#x22;span&#x22; | &#x22;div&#x22; | &#x22;strong&#x22; | &#x22;em&#x22; | &#x22;small&#x22;', default: '&#x22;p&#x22;', description: &#x22;Element to render.&#x22; },
  size: { type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Font size and line height.&#x22; },
  tone: { type: '&#x22;default&#x22; | &#x22;subtle&#x22; | &#x22;muted&#x22; | &#x22;brand&#x22; | &#x22;danger&#x22; | &#x22;success&#x22;', default: '&#x22;default&#x22;', description: &#x22;Text color.&#x22; },
  weight: { type: '&#x22;normal&#x22; | &#x22;medium&#x22; | &#x22;semibold&#x22; | &#x22;bold&#x22;', description: &#x22;Font weight. Inherits when omitted.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

### Blockquote

<TypeTable
  type="{
  attribution: { type: &#x22;ReactNode&#x22;, description: &#x22;Source shown under the quote. Wraps the quote in a <figure>.&#x22; },
  cite: { type: &#x22;string&#x22;, description: &#x22;URL of the source (native attribute).&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Applied to the <figure> when attribution is set, otherwise to the <blockquote>.&#x22; },
}"
/>

### List

<TypeTable
  type="{
  ordered: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Renders <ol> with numbers.&#x22; },
  marker: { type: '&#x22;disc&#x22; | &#x22;decimal&#x22; | &#x22;none&#x22;', description: &#x22;Overrides the marker style.&#x22; },
  spacing: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Gap between items: 4px or 8px.&#x22; },
  start: { type: &#x22;number&#x22;, description: &#x22;First number of an ordered list.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

### Prose

<TypeTable
  type="{
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Base font size; everything inside scales with it.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

`Lead`, `Small` and `Code` take the native props of `<p>`, `<small>` and `<code>`.

## Related

* [Card](/docs/components/card) — titles and descriptions inside a card.
* [Kbd](/docs/components/kbd) — keyboard keys and shortcuts.
* [Link](/docs/components/link) — standalone links with variants.

---

# Button

Source: https://desyne.dev/docs/components/button

> Triggers an action or event. Six visual styles, seven colors, eight sizes and a built-in pending state — with press handling that works the same on mouse, touch, pen and keyboard.

```tsx title="button/demo.tsx"
"use client";

import { PlusIcon } from "lucide-react";
import { Button } from "@/components/ui/button";

export default function ButtonDemo() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Button>
        <PlusIcon /> New project
      </Button>
      <Button variant="outline">Cancel</Button>
    </div>
  );
}
```

## Installation

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

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

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

```tsx
<Button onPress={() => save()}>Save changes</Button>
```

<Callout title="Use onPress, not onClick">
  React Aria normalizes mouse, touch, pen and keyboard input into a single
  `onPress` event. It fires once per press, ignores scroll gestures on touch
  devices and never leaves a "sticky" hover state behind. `onClick` still
  works, but you lose those guarantees.
</Callout>

### When to use

* Use a button to perform an action: submit a form, open a dialog, start a process.
* Use a [link](/docs/components/link) to navigate. If it changes the URL, it should be a link — style it with [`buttonVariants`](#as-a-link) if it needs to look like a button.
* Use a [toggle button](/docs/components/toggle-button) for an on/off state that persists, like bold or mute.
* Keep one `solid` button per view for the primary action; use `outline`, `soft` or `ghost` for everything else.

## Anatomy

A button is a single element. Icons, spinners and keyboard hints are plain children that the button sizes and spaces for you.

```tsx
<Button>
  <Icon />        {/* optional leading icon, auto-sized */}
  Label
  <Kbd />         {/* optional trailing hint or icon */}
</Button>
```

| Part     | Renders    | Notes                                                                                                   |
| -------- | ---------- | ------------------------------------------------------------------------------------------------------- |
| `Button` | `<button>` | Root. Carries `data-slot="button"` and all state attributes.                                            |
| Icon     | `<svg>`    | Sized by the button (`size-4`, or `size-3`/`size-3.5` for small sizes) unless you set a `size-*` class. |
| Spinner  | `<svg>`    | Injected before the label while `isPending` is true.                                                    |

## Examples

### Variants

`solid` for the primary action, `soft` and `outline` for secondary actions, `dashed` for "add" affordances, `ghost` for toolbars and dense UIs, and `link` for inline actions.

Example `button/variants`: source in https://desyne.dev/docs/components/button.md

### Colors

Every variant works with every color. `outline`, `dashed` and `ghost` default to `neutral`; the rest default to `primary`. Use `brand` for accent actions, and `danger` only for destructive ones.

Example `button/colors`: source in https://desyne.dev/docs/components/button.md

### Sizes

`md` (32px) is the default. `xs` and `sm` suit tables and toolbars, `lg` suits marketing pages and touch-first layouts.

Example `button/sizes`: source in https://desyne.dev/docs/components/button.md

### Full width

Buttons are inline by default. Add `w-full` for stacked actions in cards, forms and mobile layouts.

Example `button/block`: source in https://desyne.dev/docs/components/button.md

### With icon

Icons are sized and spaced automatically. Place them before the label for actions ("Add", "Upload") and after it for direction ("Next", external links).

Example `button/with-icon`: source in https://desyne.dev/docs/components/button.md

### Icon only

Use the `icon-xs`, `icon-sm`, `icon` and `icon-lg` sizes for square buttons. They have no visible text, so `aria-label` is required.

Example `button/icon`: source in https://desyne.dev/docs/components/button.md

### With tooltip

Pair icon-only buttons with a [`Tooltip`](/docs/components/tooltip) so sighted mouse users get the same label screen readers announce.

Example `button/tooltip`: source in https://desyne.dev/docs/components/button.md

### With keyboard shortcut

Put a [`Kbd`](/docs/components/kbd) inside the button to advertise its shortcut. The button doesn't bind the key for you — register it with your own hotkey handler.

Example `button/with-kbd`: source in https://desyne.dev/docs/components/button.md

### Button group

Wrap related buttons in a React Aria `Group` and remove the inner radii to attach them. The group gives assistive tech a single labelled region.

Example `button/group`: source in https://desyne.dev/docs/components/button.md

### Pending

`isPending` shows a spinner, blocks further presses and keeps focus on the button, so keyboard and screen-reader users aren't thrown back to the top of the page. The button also announces its busy state.

Example `button/pending`: source in https://desyne.dev/docs/components/button.md

### Async actions

Drive `isPending` from your own state to show progress and a success state for async work.

Example `button/loading`: source in https://desyne.dev/docs/components/button.md

### Disabled

`isDisabled` removes the button from the tab order and ignores presses. Prefer `isPending` while work is in flight, and consider explaining why an action is unavailable instead of silently disabling it.

Example `button/disabled`: source in https://desyne.dev/docs/components/button.md

### In a form

Buttons default to `type="button"`. Set `type="submit"` or `type="reset"` to take part in a form; native validation and `FormData` work as usual.

Example `button/form`: source in https://desyne.dev/docs/components/button.md

### As a link

Links must stay links for navigation to work (middle-click, "open in new tab", prefetching). Apply `buttonVariants` to a React Aria `Link`, Next.js `Link` or any element to borrow the button styles.

Example `button/as-link`: source in https://desyne.dev/docs/components/button.md

```tsx
import NextLink from "next/link";
import { buttonVariants } from "@/components/ui/button";

<NextLink href="/pricing" className={buttonVariants({ variant: "outline" })}>
  See pricing
</NextLink>;
```

## Recipes

### Toolbar

Ghost icon buttons inside a React Aria `Toolbar` get arrow-key navigation between items, with tooltips that show the shortcut.

Example `button/recipe-toolbar`: source in https://desyne.dev/docs/components/button.md

### Split button

A primary action attached to a [`Menu`](/docs/components/menu) of alternatives.

Example `button/recipe-split`: source in https://desyne.dev/docs/components/button.md

### Empty state

A primary and a secondary action, centered in an empty-state card.

Example `button/recipe-empty-state`: source in https://desyne.dev/docs/components/button.md

## Accessibility

* Renders a native `<button>`, so it's focusable, announced as a button and works with every assistive technology out of the box.
* The focus ring only appears for keyboard focus (`data-focus-visible`), never on mouse click.
* Icon-only buttons must have an `aria-label` (or `aria-labelledby`).
* `isPending` sets `aria-disabled` and announces the busy state, but keeps the button in the tab order so focus isn't lost.
* `isDisabled` sets the native `disabled` attribute and removes the button from the tab order.
* Don't nest interactive elements (links, other buttons) inside a button.

### Keyboard

| Key                                 | Action                    |
| ----------------------------------- | ------------------------- |
| <kbd>Tab</kbd>                      | Moves focus to the button |
| <kbd>Space</kbd> / <kbd>Enter</kbd> | Presses the button        |

## Styling

### Data attributes

Style states with Tailwind's native data variants, e.g. `data-pressed:scale-[0.98]`.

| Attribute            | Present when                                                        |
| -------------------- | ------------------------------------------------------------------- |
| `data-hovered`       | Hovered with a mouse or pen (never on touch)                        |
| `data-pressed`       | Being pressed                                                       |
| `data-focused`       | Focused by any means                                                |
| `data-focus-visible` | Focused with the keyboard                                           |
| `data-disabled`      | `isDisabled` is true                                                |
| `data-pending`       | `isPending` is true                                                 |
| `data-slot="button"` | Always — target buttons from a parent with `*:data-[slot=button]:…` |

### Tone variables

Colors are applied through two CSS variables, so you can create a one-off tone without touching the variants:

```tsx
<Button className="[--tone:var(--color-pink-600)] [--tone-fg:white]">
  Custom tone
</Button>
```

| Variable    | Used for                                                           |
| ----------- | ------------------------------------------------------------------ |
| `--tone`    | Background (`solid`), text and border (other variants), focus ring |
| `--tone-fg` | Text on `solid` buttons                                            |

### Render props

`className` and `children` also accept a function of the button's state:

```tsx
<Button className={({ isPressed }) => (isPressed ? "scale-95" : "")}>
  {({ isPending }) => (isPending ? "Saving…" : "Save")}
</Button>
```

### `buttonVariants`

The `tailwind-variants` function behind the component. Use it to style non-button elements, or to build your own variants on top.

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

buttonVariants({ variant: "soft", color: "success", size: "sm" });
```

## API Reference

### Button

<TypeTable
  type="{
  variant: {
    type: '&#x22;solid&#x22; | &#x22;soft&#x22; | &#x22;outline&#x22; | &#x22;dashed&#x22; | &#x22;ghost&#x22; | &#x22;link&#x22;',
    default: '&#x22;solid&#x22;',
    description: 'Visual style. The shadcn names &#x22;default&#x22;, &#x22;destructive&#x22; and &#x22;secondary&#x22; are accepted as aliases.',
  },
  color: {
    type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;',
    description: 'Color tone. Defaults to &#x22;primary&#x22; for solid, soft and link; &#x22;neutral&#x22; for outline, dashed and ghost.',
  },
  size: {
    type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;icon-xs&#x22; | &#x22;icon-sm&#x22; | &#x22;icon&#x22; | &#x22;icon-lg&#x22;',
    default: '&#x22;md&#x22;',
    description: 'Height and padding. &#x22;default&#x22; is accepted as a shadcn alias for &#x22;md&#x22;.',
  },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press is released over the button.&#x22; },
  onPressStart: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press starts.&#x22; },
  onPressEnd: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press ends, whether or not it was released over the button.&#x22; },
  onPressChange: { type: &#x22;(isPressed: boolean) => void&#x22;, description: &#x22;Called when the pressed state changes.&#x22; },
  onPressUp: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press is released, even if it started elsewhere.&#x22; },
  isPending: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shows a spinner, blocks presses and announces the busy state while keeping focus.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the button and removes it from the tab order.&#x22; },
  type: { type: '&#x22;button&#x22; | &#x22;submit&#x22; | &#x22;reset&#x22;', default: '&#x22;button&#x22;', description: &#x22;Native button type for form participation.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the button belongs to, when it's rendered outside it.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Submitted with the form data along with value.&#x22; },
  value: { type: &#x22;string&#x22;, description: &#x22;Submitted with the form data along with name.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, description: &#x22;Focuses the button on mount.&#x22; },
  slot: { type: &#x22;string | null&#x22;, description: 'React Aria slot, e.g. &#x22;close&#x22; inside a Dialog.' },
  className: { type: &#x22;string | ((state: ButtonRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: ButtonRenderProps) => ReactNode)&#x22;, description: &#x22;Content, or a function of the render state.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required for icon-only buttons.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Button`](https://react-aria.adobe.com/Button#api), including focus, hover and keyboard handlers.

### buttonVariants

<TypeTable
  type="{
  variant: { type: &#x22;ButtonProps['variant']&#x22;, default: '&#x22;solid&#x22;' },
  color: { type: &#x22;Tone&#x22;, description: &#x22;No default — pass one explicitly when styling non-button elements.&#x22; },
  size: { type: &#x22;ButtonProps['size']&#x22;, default: '&#x22;md&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Toggle Button](/docs/components/toggle-button) — a button with a persistent on/off state.
* [Toggle Button Group](/docs/components/toggle-button-group) — single or multiple selection across a set of buttons.
* [Link](/docs/components/link) — for navigation.
* [Menu](/docs/components/menu) — for a button that opens a list of actions.

---

# Toggle Button

Source: https://desyne.dev/docs/components/toggle-button

> A button that switches between on and off, like bold, mute or star. Announced as a pressed toggle, works with mouse, touch and keyboard, and picks up its style from a surrounding toggle button group.

```tsx title="toggle-button/demo.tsx"
"use client";

import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";
import { ToggleButton } from "@/components/ui/toggle-button";

export default function ToggleButtonDemo() {
  return (
    <div className="flex gap-1">
      <ToggleButton aria-label="Bold" defaultSelected>
        <BoldIcon />
      </ToggleButton>
      <ToggleButton aria-label="Italic">
        <ItalicIcon />
      </ToggleButton>
      <ToggleButton aria-label="Underline">
        <UnderlineIcon />
      </ToggleButton>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/toggle-button
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { ToggleButton } from "@/components/ui/toggle-button";
```

```tsx
<ToggleButton aria-label="Bold" defaultSelected>
  <BoldIcon />
</ToggleButton>
```

<Callout title="The label describes the action, not the state">
  A toggle button is announced with `aria-pressed`, so screen readers already
  say whether it is on. Keep the label constant ("Mute", "Bold") and let the
  pressed state carry the meaning. Swapping the label to "Unmute" while it is
  pressed reads as "Unmute, pressed", which is ambiguous.
</Callout>

### When to use

* Toggle button — an on/off state that applies immediately and persists, usually in a toolbar: bold, mute, pin, star.
* [Toggle Button Group](/docs/components/toggle-button-group) — a set of related toggles, with single selection (a segmented control) or multiple selection (a formatting bar).
* [Switch](/docs/components/switch) — a labelled on/off setting in a form or settings list.
* [Checkbox](/docs/components/checkbox) — a choice that is submitted with a form.
* [Button](/docs/components/button) — a one-off action with no persistent state.

## Anatomy

A toggle button is a single element. Icons and text are plain children, sized and spaced for you.

```tsx
<ToggleButton>
  <Icon />   {/* optional, auto-sized */}
  Label
</ToggleButton>
```

| Part           | Renders                 | Notes                                                                                                                                              |
| -------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ToggleButton` | `<button aria-pressed>` | Root. Carries `data-slot="toggle-button"` and all state attributes. Inside a single-selection group it becomes `role="radio"` with `aria-checked`. |
| Icon           | `<svg>`                 | Sized `size-4` (`size-3` / `size-3.5` for `xs` / `sm`) unless you pass a `size-*` class.                                                           |

## Examples

### Variants

`default` is borderless and fills with the accent color when selected, which suits toolbars. `outline` has a border and turns brand-tinted when selected, which reads better as a standalone control. A third variant, `segmented`, is applied automatically inside a segmented [`ToggleButtonGroup`](/docs/components/toggle-button-group).

Example `toggle-button/variants`: source in https://desyne.dev/docs/components/toggle-button.md

### With icon and label

Put an icon before the label for standalone toggles like Star, Pin or Watch. The label keeps the control understandable without a tooltip.

Example `toggle-button/outline`: source in https://desyne.dev/docs/components/toggle-button.md

### Sizes

`md` (32px) is the default. `xs` and `sm` fit dense toolbars and table rows; `lg` suits touch-first controls like call or player bars. Every size has a matching minimum width, so icon-only toggles stay square.

Example `toggle-button/sizes`: source in https://desyne.dev/docs/components/toggle-button.md

### Controlled

Use `isSelected` and `onChange` to own the state, for example to persist it or to react to it elsewhere on the page. Use `defaultSelected` when the button can manage itself.

Example `toggle-button/controlled`: source in https://desyne.dev/docs/components/toggle-button.md

### Render props

`children` and `className` accept a function of the button's state. Use it to fill or swap the icon for the selected state without lifting state up, while the label stays the same.

Example `toggle-button/render-props`: source in https://desyne.dev/docs/components/toggle-button.md

### With tooltip

Icon-only toggles need an `aria-label`. Wrap them in a [`TooltipTrigger`](/docs/components/tooltip) so mouse users see the same label.

Example `toggle-button/tooltip`: source in https://desyne.dev/docs/components/toggle-button.md

### Disabled

`isDisabled` removes the button from the tab order and keeps its current state visible, so users can still see whether it is on.

Example `toggle-button/disabled`: source in https://desyne.dev/docs/components/toggle-button.md

### Custom selected style

Style the selected state with Tailwind's `data-selected:` variant. Here the icon fills in and takes the destructive or brand color instead of the default accent background.

Example `toggle-button/custom-style`: source in https://desyne.dev/docs/components/toggle-button.md

## Recipes

### Post actions

A like toggle with a live count and a save toggle, next to a regular comment button. The accessible label includes the count so it's announced too.

Example `toggle-button/recipe-post-actions`: source in https://desyne.dev/docs/components/toggle-button.md

### Media player

A compact player bar mixing toggle buttons (like, shuffle, play/pause, repeat) with plain buttons (previous, next). The play toggle uses a render prop to swap icons.

Example `toggle-button/recipe-player`: source in https://desyne.dev/docs/components/toggle-button.md

### Filter chips

Rounded outline toggles that each switch a filter on or off, driving a filtered list. Use independent toggles like this when filters combine freely; use a [`ToggleButtonGroup`](/docs/components/toggle-button-group) with `selectionMode="multiple"` when you want the group to be one keyboard stop.

Example `toggle-button/recipe-filter-chips`: source in https://desyne.dev/docs/components/toggle-button.md

## Accessibility

* Renders a native `<button>` with `aria-pressed`, so it is announced as a toggle button along with its pressed state.
* Inside a single-selection `ToggleButtonGroup`, React Aria switches it to `role="radio"` with `aria-checked`.
* Icon-only toggles must have an `aria-label` (or `aria-labelledby`). Keep the label the same in both states.
* The focus ring only appears for keyboard focus (`data-focus-visible`).
* `isDisabled` sets the native `disabled` attribute and removes the button from the tab order.

### Keyboard

| Key                                 | Action                    |
| ----------------------------------- | ------------------------- |
| <kbd>Tab</kbd>                      | Moves focus to the button |
| <kbd>Space</kbd> / <kbd>Enter</kbd> | Toggles the button        |

## Styling

### Data attributes

Style states with Tailwind's data variants, e.g. `data-selected:text-brand`.

| Attribute                   | Present when                                      |
| --------------------------- | ------------------------------------------------- |
| `data-selected`             | The button is on                                  |
| `data-hovered`              | Hovered with a mouse or pen (never on touch)      |
| `data-pressed`              | Being pressed                                     |
| `data-focused`              | Focused by any means                              |
| `data-focus-visible`        | Focused with the keyboard                         |
| `data-disabled`             | `isDisabled` is true (directly or from the group) |
| `data-slot="toggle-button"` | Always                                            |

### Render props

`className` and `children` also accept a function of the button's state:

```tsx
<ToggleButton
  aria-label="Mute"
  className={({ isSelected }) => (isSelected ? "text-destructive" : "")}
>
  {({ isSelected }) => (isSelected ? <VolumeXIcon /> : <Volume2Icon />)}
</ToggleButton>
```

### `toggleVariants`

The `tailwind-variants` function behind the component. Use it to give another element the toggle look, or to extend the variants.

```tsx
import { toggleVariants } from "@/components/ui/toggle-button";

toggleVariants({ variant: "outline", size: "sm" });
```

`ToggleGroupStyleContext` is also exported. `ToggleButtonGroup` uses it to pass `variant` and `size` down; props set directly on a `ToggleButton` win over the context.

## API Reference

### ToggleButton

<TypeTable
  type="{
  variant: {
    type: '&#x22;default&#x22; | &#x22;outline&#x22; | &#x22;segmented&#x22;',
    default: '&#x22;default&#x22;',
    description: &#x22;Visual style. Inherited from a surrounding ToggleButtonGroup when not set.&#x22;,
  },
  size: {
    type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;',
    default: '&#x22;md&#x22;',
    description: &#x22;Height, minimum width and padding. Inherited from a surrounding ToggleButtonGroup when not set.&#x22;,
  },
  isSelected: { type: &#x22;boolean&#x22;, description: &#x22;Controlled selected state.&#x22; },
  defaultSelected: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Uncontrolled initial selected state.&#x22; },
  onChange: { type: &#x22;(isSelected: boolean) => void&#x22;, description: &#x22;Called when the selected state changes.&#x22; },
  id: { type: &#x22;Key&#x22;, description: &#x22;Inside a ToggleButtonGroup, the key used in selectedKeys. Standalone, the DOM id.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the button and removes it from the tab order.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press is released over the button.&#x22; },
  onPressStart: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press starts.&#x22; },
  onPressEnd: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when a press ends.&#x22; },
  onPressChange: { type: &#x22;(isPressed: boolean) => void&#x22;, description: &#x22;Called when the pressed state changes.&#x22; },
  onHoverStart: { type: &#x22;(e: HoverEvent) => void&#x22;, description: &#x22;Called when a hover starts.&#x22; },
  onHoverEnd: { type: &#x22;(e: HoverEvent) => void&#x22;, description: &#x22;Called when a hover ends.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, description: &#x22;Focuses the button on mount.&#x22; },
  slot: { type: &#x22;string | null&#x22;, description: &#x22;React Aria slot name.&#x22; },
  className: { type: &#x22;string | ((state: ToggleButtonRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: ToggleButtonRenderProps) => ReactNode)&#x22;, description: &#x22;Content, or a function of the render state.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required for icon-only buttons.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ToggleButton`](https://react-aria.adobe.com/ToggleButton#api), including focus and keyboard handlers.

### toggleVariants

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;outline&#x22; | &#x22;segmented&#x22;', default: '&#x22;default&#x22;' },
  size: { type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Toggle Button Group](/docs/components/toggle-button-group) — single or multiple selection across a set of toggle buttons.
* [Button](/docs/components/button) — for one-off actions.
* [Switch](/docs/components/switch) — a labelled on/off setting.
* [Tooltip](/docs/components/tooltip) — labels for icon-only toggles.

---

# Toggle Button Group

Source: https://desyne.dev/docs/components/toggle-button-group

> A set of toggle buttons with single or multiple selection. Use it as an attached button bar, a segmented control or a spaced toolbar; it's one tab stop with arrow-key navigation, and passes its variant and size down to every button.

```tsx title="toggle-button-group/demo.tsx"
"use client";

import {
  AlignCenterIcon,
  AlignJustifyIcon,
  AlignLeftIcon,
  AlignRightIcon,
} from "lucide-react";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";

export default function ToggleButtonGroupDemo() {
  return (
    <ToggleButtonGroup
      aria-label="Text alignment"
      defaultSelectedKeys={["left"]}
      disallowEmptySelection
    >
      <ToggleButton id="left" aria-label="Align left">
        <AlignLeftIcon />
      </ToggleButton>
      <ToggleButton id="center" aria-label="Align center">
        <AlignCenterIcon />
      </ToggleButton>
      <ToggleButton id="right" aria-label="Align right">
        <AlignRightIcon />
      </ToggleButton>
      <ToggleButton id="justify" aria-label="Justify">
        <AlignJustifyIcon />
      </ToggleButton>
    </ToggleButtonGroup>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/toggle-button-group
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";
```

```tsx
<ToggleButtonGroup
  aria-label="View"
  defaultSelectedKeys={["list"]}
  disallowEmptySelection
>
  <ToggleButton id="list">List</ToggleButton>
  <ToggleButton id="board">Board</ToggleButton>
</ToggleButtonGroup>
```

Give every `ToggleButton` an `id`: that's the key used in `selectedKeys`. The group passes its `variant` and `size` to its buttons, so you don't repeat them on each one.

<Callout title="Add disallowEmptySelection for segmented controls">
  By default, pressing the selected button in a single-selection group
  deselects it, leaving nothing selected. For view switchers, tabs-like
  controls and billing toggles, set `disallowEmptySelection` so one option is
  always active.
</Callout>

### When to use

* Toggle Button Group — a small set (2–6) of options that apply immediately, like a view switcher, a time range or text formatting.
* [Toggle Button](/docs/components/toggle-button) — a single, independent on/off control.
* [Radio Group](/docs/components/radio-group) — a labelled choice in a form, especially with descriptions.
* [Tabs](/docs/components/tabs) — switching between panels of content, with a tab panel for each option.
* [Select](/docs/components/select) — more options than fit on one line.

## Anatomy

```tsx
<ToggleButtonGroup>        {/* toolbar or radiogroup, passes variant + size */}
  <ToggleButton id="…" />  {/* one per option */}
</ToggleButtonGroup>
```

| Part                | Renders                                             | Notes                                                                                                                                                                          |
| ------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ToggleButtonGroup` | `<div role="radiogroup">` or `<div role="toolbar">` | `radiogroup` for `selectionMode="single"`, `toolbar` for `"multiple"`. Nested in a React Aria `Toolbar`, it becomes `role="group"`. Carries `data-slot="toggle-button-group"`. |
| `ToggleButton`      | `<button>`                                          | An option. `role="radio"` in single mode, `aria-pressed` in multiple mode. See [Toggle Button](/docs/components/toggle-button).                                                |

## Examples

### Variants

`attached` (default) joins bordered buttons into one bar. `segmented` is a pill track with a raised selection. `spaced` keeps borderless buttons separate with a small gap, which suits toolbars. The group sets its buttons to `outline`, `segmented` and `default` respectively.

Example `toggle-button-group/variants`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Segmented

A segmented control for switching views, time ranges or modes. Pair it with `disallowEmptySelection` so an option is always selected.

Example `toggle-button-group/segmented`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Sizes

`size` is passed to every button, from `xs` (24px) to `lg` (40px). A `size` set on an individual `ToggleButton` wins over the group's.

Example `toggle-button-group/sizes`: source in https://desyne.dev/docs/components/toggle-button-group.md

### With icons

Icons combine with labels in segmented controls. Icon-only buttons need an `aria-label` each.

Example `toggle-button-group/icons`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Multiple selection

`selectionMode="multiple"` lets any number of buttons be on at once, like a formatting bar. The group is then a `toolbar` and each button announces `aria-pressed`.

Example `toggle-button-group/multiple`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Vertical

`orientation="vertical"` stacks the buttons and switches keyboard navigation to <kbd>↑</kbd> / <kbd>↓</kbd>. All three variants support it.

Example `toggle-button-group/vertical`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Controlled

Use `selectedKeys` and `onSelectionChange` to own the selection. The callback receives a `Set` of keys in both single and multiple mode. Here a weekday picker uses `spaced` with `outline` buttons set directly on each item.

Example `toggle-button-group/controlled`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Disabled

`isDisabled` on the group disables every button; `isDisabled` on a single `ToggleButton` disables just that option, for example a format that isn't available on the current plan.

Example `toggle-button-group/disabled`: source in https://desyne.dev/docs/components/toggle-button-group.md

## Recipes

### View switcher

A small icon-only segmented control in a section header that switches a file list between grid and list layouts.

Example `toggle-button-group/recipe-view-switcher`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Editor toolbar

Several groups inside one React Aria `Toolbar`: multiple selection for styles, single selection for alignment, with [`Tooltip`](/docs/components/tooltip)s that show shortcuts. The toolbar owns arrow-key navigation across all groups, so the whole bar is one tab stop.

Example `toggle-button-group/recipe-editor-toolbar`: source in https://desyne.dev/docs/components/toggle-button-group.md

### Billing toggle

A full-width segmented control (`*:flex-1`) that switches a pricing card between monthly and yearly billing, with a [`Badge`](/docs/components/badge) for the discount.

Example `toggle-button-group/recipe-pricing`: source in https://desyne.dev/docs/components/toggle-button-group.md

## Accessibility

* In single-selection mode the group is a `radiogroup` and each button is a `radio` with `aria-checked`; in multiple mode it's a `toolbar` and each button uses `aria-pressed`.
* The group is labelled with `aria-label` or `aria-labelledby`. Always describe what it controls ("Text alignment", "View as").
* Arrow keys move focus between buttons. <kbd>Tab</kbd> leaves the group, and focus returns to the last focused button when you tab back in.
* Inside a React Aria `Toolbar`, the group becomes a `group` and the toolbar handles arrow keys, so several groups share one tab stop.
* Arrow-key direction is reversed in right-to-left locales for horizontal groups.

### Keyboard

| Key                                              | Action                                   |
| ------------------------------------------------ | ---------------------------------------- |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus into or out of the group     |
| <kbd>←</kbd> / <kbd>→</kbd>                      | Moves focus between buttons (horizontal) |
| <kbd>↑</kbd> / <kbd>↓</kbd>                      | Moves focus between buttons (vertical)   |
| <kbd>Space</kbd> / <kbd>Enter</kbd>              | Toggles the focused button               |

## Styling

### Data attributes

On the `ToggleButtonGroup`:

| Attribute                         | Present when                                                                                         |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `data-orientation`                | Always, `"horizontal"` or `"vertical"`; the variants use it to switch between row and column layouts |
| `data-disabled`                   | `isDisabled` is true                                                                                 |
| `data-slot="toggle-button-group"` | Always                                                                                               |

Each `ToggleButton` has the usual `data-selected`, `data-hovered`, `data-pressed`, `data-focus-visible` and `data-disabled` attributes. See [Toggle Button](/docs/components/toggle-button#data-attributes).

### Customizing

* `className` on the group styles the container. Use child selectors to style the buttons in bulk, e.g. `*:flex-1` for equal-width segments or `w-full` for a full-width bar.
* `attached` strips the buttons' radius and shadow and overlaps borders by 1px; the selected button is raised with `z-[1]` so its brand border stays visible.
* To use a different item style than the group's default, set `variant` on each `ToggleButton`; it overrides the value from context.

### Render props

`className` accepts a function of the group's state:

```tsx
<ToggleButtonGroup
  className={({ orientation }) => (orientation === "vertical" ? "w-40" : "")}
/>
```

## API Reference

### ToggleButtonGroup

<TypeTable
  type="{
  variant: {
    type: '&#x22;attached&#x22; | &#x22;segmented&#x22; | &#x22;spaced&#x22;',
    default: '&#x22;attached&#x22;',
    description: &#x22;Layout of the group. Sets the buttons' variant to outline, segmented or default.&#x22;,
  },
  size: { type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', description: &#x22;Size applied to every button in the group (buttons default to md).&#x22; },
  selectionMode: { type: '&#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;single&#x22;', description: &#x22;Whether one or many buttons can be selected.&#x22; },
  selectedKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Set<Key>) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Prevents deselecting the last selected button.&#x22; },
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Layout direction and arrow-key axis.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables every button in the group.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name for the group.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of an element that labels the group.&#x22; },
  slot: { type: &#x22;string | null&#x22;, description: &#x22;React Aria slot name.&#x22; },
  className: { type: &#x22;string | ((state: ToggleButtonGroupRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: ToggleButtonGroupRenderProps) => ReactNode)&#x22;, description: &#x22;ToggleButtons.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ToggleButtonGroup`](https://react-aria.adobe.com/ToggleButtonGroup#api).

### ToggleButton

Inside a group, `id` is required and `isSelected`, `defaultSelected` and `onChange` are ignored in favor of the group's selection. See the [Toggle Button API](/docs/components/toggle-button#api-reference) for the rest.

## Related

* [Toggle Button](/docs/components/toggle-button) — the individual buttons.
* [Radio Group](/docs/components/radio-group) — single choice in a form.
* [Tabs](/docs/components/tabs) — switch between panels of content.
* [Button](/docs/components/button) — attach plain action buttons with a React Aria `Group`.

---

# Toolbar

Source: https://desyne.dev/docs/components/toolbar

> A row or column of buttons, toggles and menus that acts as a single tab stop, with arrow-key navigation between controls. Includes groups, separators that follow the orientation, and plain, outline and floating styles.

```tsx title="toolbar/demo.tsx"
"use client";

import {
  AlignCenterIcon,
  AlignLeftIcon,
  AlignRightIcon,
  BoldIcon,
  ItalicIcon,
  LinkIcon,
  ListIcon,
  ListOrderedIcon,
  UnderlineIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { ToggleButton } from "@/components/ui/toggle-button";
import { ToggleButtonGroup } from "@/components/ui/toggle-button-group";
import {
  Toolbar,
  ToolbarGroup,
  ToolbarSeparator,
} from "@/components/ui/toolbar";

export default function ToolbarDemo() {
  return (
    <Toolbar aria-label="Text formatting" variant="outline">
      <ToolbarGroup aria-label="Style">
        <ToggleButton size="sm" aria-label="Bold" defaultSelected>
          <BoldIcon />
        </ToggleButton>
        <ToggleButton size="sm" aria-label="Italic">
          <ItalicIcon />
        </ToggleButton>
        <ToggleButton size="sm" aria-label="Underline">
          <UnderlineIcon />
        </ToggleButton>
      </ToolbarGroup>
      <ToolbarSeparator />
      <ToggleButtonGroup
        aria-label="Alignment"
        variant="spaced"
        size="sm"
        selectionMode="single"
        disallowEmptySelection
        defaultSelectedKeys={["left"]}
        className="gap-0.5"
      >
        <ToggleButton id="left" aria-label="Align left">
          <AlignLeftIcon />
        </ToggleButton>
        <ToggleButton id="center" aria-label="Align center">
          <AlignCenterIcon />
        </ToggleButton>
        <ToggleButton id="right" aria-label="Align right">
          <AlignRightIcon />
        </ToggleButton>
      </ToggleButtonGroup>
      <ToolbarSeparator />
      <ToolbarGroup aria-label="Insert">
        <Button variant="ghost" size="icon-sm" aria-label="Bulleted list">
          <ListIcon />
        </Button>
        <Button variant="ghost" size="icon-sm" aria-label="Numbered list">
          <ListOrderedIcon />
        </Button>
        <Button variant="ghost" size="icon-sm" aria-label="Insert link">
          <LinkIcon />
        </Button>
      </ToolbarGroup>
    </Toolbar>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/toolbar
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { Toolbar, ToolbarGroup, ToolbarSeparator } from "@/components/ui/toolbar";
```

```tsx
<Toolbar aria-label="Text formatting">
  <ToolbarGroup aria-label="Style">
    <ToggleButton aria-label="Bold"><BoldIcon /></ToggleButton>
    <ToggleButton aria-label="Italic"><ItalicIcon /></ToggleButton>
  </ToolbarGroup>
  <ToolbarSeparator />
  <Button variant="ghost" size="icon-sm" aria-label="Insert link"><LinkIcon /></Button>
</Toolbar>
```

Put any [Button](/docs/components/button), [Toggle Button](/docs/components/toggle-button), [Toggle Button Group](/docs/components/toggle-button-group) or [Menu](/docs/components/menu) trigger inside. The toolbar doesn't style its children, so pick ghost buttons and a small size to match.

### When to use

* Toolbar — a set of related commands for one area: editor formatting, canvas tools, bulk actions on selected rows, a document header.
* A plain flex row of buttons — two or three unrelated actions such as Cancel and Save. Those should each be tab stops.
* [Toggle Button Group](/docs/components/toggle-button-group) — a single choice or multi-choice set on its own. Inside a toolbar it becomes one of the toolbar's groups.
* [Menu](/docs/components/menu) — when commands don't fit, move the rest behind a "More" menu trigger in the toolbar.

## Anatomy

```tsx
<Toolbar>                 {/* role="toolbar" */}
  <ToolbarGroup>          {/* role="group" */}
    <Button />
  </ToolbarGroup>
  <ToolbarSeparator />    {/* role="separator", perpendicular to the toolbar */}
  <MenuTrigger />
</Toolbar>
```

| Part               | Renders                  | Notes                                                                                                              |
| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `Toolbar`          | `<div role="toolbar">`   | React Aria `Toolbar`. Sets `aria-orientation` and manages arrow-key focus. `data-orientation` drives the layout.   |
| `ToolbarGroup`     | `<div role="group">`     | Groups related controls. Label it with `aria-label`.                                                               |
| `ToolbarSeparator` | `<div role="separator">` | A vertical line in a horizontal toolbar and a horizontal line in a vertical one, with matching `aria-orientation`. |

## Examples

### Vertical

`orientation="vertical"` stacks the controls, for tool palettes on a canvas. Up and down arrows move focus. Separators turn horizontal on their own. Pass `orientation="vertical"` to a nested `ToggleButtonGroup` too.

Example `toolbar/vertical`: source in https://desyne.dev/docs/components/toolbar.md

### Variants

`plain` (default) has no frame, for headers and editor chrome. `outline` draws a bordered bar on the card surface. `floating` uses the popover surface and a larger shadow, for bars that hover over content.

Example `toolbar/variants`: source in https://desyne.dev/docs/components/toolbar.md

### Bulk actions

A `floating` toolbar for actions on selected rows, with a live count. Keep text fields such as search outside the toolbar: the toolbar uses <kbd>←</kbd> and <kbd>→</kbd> to move focus, which would stop the cursor moving inside the input.

Example `toolbar/table-actions`: source in https://desyne.dev/docs/components/toolbar.md

### With a menu

A [Menu](/docs/components/menu) trigger works like any other button in the toolbar: arrow keys reach it, and <kbd>Enter</kbd>, <kbd>Space</kbd> or <kbd>↓</kbd> opens it. Disabled buttons are skipped by arrow keys.

Example `toolbar/with-menu`: source in https://desyne.dev/docs/components/toolbar.md

## Accessibility

* The toolbar is one tab stop. <kbd>Tab</kbd> moves focus into it (to the last focused control) and out of it; arrow keys move between controls.
* Every toolbar needs an accessible name: `aria-label` or `aria-labelledby`. Label each `ToolbarGroup` too, so screen readers announce "Alignment, group" when focus enters it.
* Icon-only buttons need `aria-label`. Add a [Tooltip](/docs/components/tooltip) with the same text (and the shortcut) for sighted users.
* Use `ToggleButton` for on/off formatting, so the pressed state is announced, and `ToggleButtonGroup` with `selectionMode="single"` for mutually exclusive options such as alignment.
* In right-to-left locales, <kbd>←</kbd> and <kbd>→</kbd> are reversed in a horizontal toolbar.

### Keyboard

| Key                                              | Action                                 |
| ------------------------------------------------ | -------------------------------------- |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus into or out of the toolbar |
| <kbd>→</kbd> / <kbd>←</kbd>                      | Next / previous control (horizontal)   |
| <kbd>↓</kbd> / <kbd>↑</kbd>                      | Next / previous control (vertical)     |
| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused control          |

## Styling

### Data attributes

| Attribute          | On        | Present when                             |
| ------------------ | --------- | ---------------------------------------- |
| `data-orientation` | `Toolbar` | Always: `horizontal` or `vertical`       |
| `data-variant`     | `Toolbar` | Always: `plain`, `outline` or `floating` |

### Data slots

| Slot                            | Element     |
| ------------------------------- | ----------- |
| `data-slot="toolbar"`           | Root        |
| `data-slot="toolbar-group"`     | A group     |
| `data-slot="toolbar-separator"` | A separator |

A horizontal toolbar scrolls sideways when it's wider than its container. To wrap instead, pass `className="flex-wrap overflow-visible"`.

## API Reference

### Toolbar

<TypeTable
  type="{
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Layout and arrow-key direction.&#x22; },
  variant: { type: '&#x22;plain&#x22; | &#x22;outline&#x22; | &#x22;floating&#x22;', default: '&#x22;plain&#x22;', description: &#x22;Frame around the controls.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required unless aria-labelledby is set.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of an element that labels the toolbar.&#x22; },
  className: { type: &#x22;string | ((state: ToolbarRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of { orientation }.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Toolbar`](https://react-aria.adobe.com/Toolbar#api).

### ToolbarGroup

<TypeTable
  type="{
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Names the group.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Marks the group disabled (data-disabled). Disable the controls themselves too.&#x22; },
  className: { type: &#x22;string | ((state: GroupRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Group`](https://react-aria.adobe.com/Group#api).

### ToolbarSeparator

Takes React Aria's [`Separator`](https://react-aria.adobe.com/Separator#api) props. `orientation` is set from the toolbar; pass it only to override.

## Related

* [Toggle Button Group](/docs/components/toggle-button-group) — exclusive or multiple toggles, often a toolbar group.
* [Menu](/docs/components/menu) — overflow commands behind a trigger.
* [Tooltip](/docs/components/tooltip) — labels for icon buttons.

---

# Form

Source: https://desyne.dev/docs/components/form

> React Aria's Form with consistent spacing, live validation by default and server-side errors mapped onto fields by name. Includes FormSection (fieldset + legend), FormRow for side-by-side fields and FormActions for the button row.

```tsx title="form/demo.tsx"
"use client";

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Checkbox } from "@/components/ui/checkbox";
import { Form, FormActions, FormRow } from "@/components/ui/form";
import { TextField } from "@/components/ui/text-field";

export default function FormDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);
  return (
    <Form
      className="max-w-md"
      onSubmit={(e) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget);
        setSubmitted(String(data.get("firstName")));
      }}
    >
      <FormRow>
        <TextField label="First name" name="firstName" isRequired />
        <TextField label="Last name" name="lastName" isRequired />
      </FormRow>
      <TextField
        label="Work email"
        name="email"
        type="email"
        placeholder="you@company.com"
        isRequired
      />
      <TextField
        label="Password"
        name="password"
        type="password"
        description="At least 8 characters."
        minLength={8}
        isRequired
      />
      <Checkbox name="terms" value="accepted" isRequired>
        I agree to the terms of service
      </Checkbox>
      <FormActions align="between">
        <p className="text-muted-foreground text-sm" aria-live="polite">
          {submitted ? `Welcome aboard, ${submitted}.` : null}
        </p>
        <Button type="submit">Create account</Button>
      </FormActions>
    </Form>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/form
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { Form, FormActions, FormRow, FormSection } from "@/components/ui/form";
```

```tsx
<Form onSubmit={handleSubmit} validationErrors={serverErrors}>
  <FormSection title="Contact" description="Where we send receipts.">
    <FormRow>
      <TextField label="First name" name="firstName" isRequired />
      <TextField label="Last name" name="lastName" isRequired />
    </FormRow>
    <TextField label="Email" name="email" type="email" isRequired />
  </FormSection>
  <FormActions>
    <Button type="submit">Save</Button>
  </FormActions>
</Form>
```

Every field in this library (`TextField`, `Select`, `DatePicker`, `Checkbox`, …) reads its validation settings from the surrounding `Form`, so you set them once.

<Callout title="Validation is live by default">
  React Aria's own default is `validationBehavior="native"`, where the browser
  blocks submit and errors appear only after a submit attempt. This `Form`
  defaults to `"aria"`: errors appear as soon as a field is committed (on blur
  or change) and nothing blocks `onSubmit`, so you decide what to do with an
  invalid form. Pass `validationBehavior="native"` to get the browser behavior
  back.
</Callout>

### When to use

* `Form` — any group of inputs that's submitted together: sign-up, checkout, settings, filters.
* `FormSection` — related fields inside a long form (Profile, Billing, Notifications). It's a real `<fieldset>`, so the title names the group for screen readers.
* `FormRow` — two to four short fields that belong on one line (first and last name; city, state and ZIP).
* `FormActions` — the submit and cancel buttons, aligned and spaced consistently.
* A single field that saves on its own (a search box, an inline rename) doesn't need a form.

## Anatomy

```tsx
<Form>                       {/* <form> */}
  <FormSection>              {/* <fieldset> */}
    {/* <legend>title</legend> + <p>description</p> */}
    <FormRow>                {/* <div> grid */}
      <TextField />
      <TextField />
    </FormRow>
  </FormSection>
  <FormActions>              {/* <div> */}
    <Button type="submit" />
  </FormActions>
</Form>
```

| Part          | Renders      | Notes                                                                                                                                                          |
| ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Form`        | `<form>`     | React Aria `Form`. Provides `validationBehavior` and `validationErrors` to every field inside. `layout` and `gap` set the spacing.                             |
| `FormSection` | `<fieldset>` | Groups fields. `title` renders a `<legend>`, `description` is linked with `aria-describedby`. `layout="aside"` puts the text in a left column on wide screens. |
| `FormRow`     | `<div>`      | A grid of 2, 3 or 4 columns that collapses to one column on small screens. Fields align to the top so error messages don't push neighbors around.              |
| `FormActions` | `<div>`      | A wrapping row of buttons. `align` sets start, end or space-between; `separator` adds a top border.                                                            |

## Examples

### Validation

Fields validate themselves with HTML constraints (`isRequired`, `type="email"`, `minLength`, `pattern`, `minValue`/`maxValue`) and with a `validate` function for custom rules. `validate` returns an error message, an array of messages, or `null` when the value is fine. Messages use the browser's localized text unless you return your own. Submitting focuses the first invalid field.

Example `form/validation`: source in https://desyne.dev/docs/components/form.md

### Server errors

Pass an object of `{ [fieldName]: message }` to `validationErrors`. Each field shows the message whose key matches its `name` and is marked invalid. The error clears as soon as the user edits that field, so they aren't stuck looking at a stale message. Try submitting the defaults, then change one field.

Example `form/server-errors`: source in https://desyne.dev/docs/components/form.md

With a Next.js server action, return the errors from the action and hand them to the form:

```tsx title="app/workspaces/new/actions.ts"
"use server";

export async function createWorkspace(_prev: State, data: FormData): Promise<State> {
  const slug = String(data.get("slug"));
  if (await db.workspace.exists({ slug })) {
    return { errors: { slug: `“${slug}” is already taken.` } };
  }
  await db.workspace.create({ slug });
  redirect(`/${slug}`);
}
```

```tsx title="app/workspaces/new/form.tsx"
"use client";

import { useActionState } from "react";
import { createWorkspace } from "./actions";

export function NewWorkspaceForm() {
  const [state, action, pending] = useActionState(createWorkspace, { errors: {} });
  return (
    <Form action={action} validationErrors={state.errors}>
      <TextField label="Workspace URL" name="slug" isRequired />
      <FormActions>
        <Button type="submit" isPending={pending}>Create workspace</Button>
      </FormActions>
    </Form>
  );
}
```

React resets uncontrolled fields after a form action finishes. If you want to keep what the user typed when there are errors, return their values too and pass them as `defaultValue`, or use `onSubmit` as in the example above.

### Schema validation (Zod)

Validate the whole form against a schema on submit and feed the resulting field errors to `validationErrors`. With [Zod](https://zod.dev) that's `safeParse` plus `flatten().fieldErrors`:

```tsx
import { z } from "zod";

const shipping = z.object({
  name: z.string().min(1, "Enter the recipient's name."),
  address: z.string().min(5, "That address looks too short."),
  postcode: z.string().regex(/^\d{5}(-\d{4})?$/, "Use a 5-digit ZIP code, like 94107."),
  country: z.enum(["US", "CA", "MX"], { message: "Choose a country." }),
});

function onSubmit(e: React.FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const result = shipping.safeParse(Object.fromEntries(new FormData(e.currentTarget)));
  if (!result.success) {
    setErrors(result.error.flatten().fieldErrors); // { postcode: ["Use a 5-digit…"] }
    return;
  }
  save(result.data); // fully typed
}

<Form validationErrors={errors} onSubmit={onSubmit}>…</Form>
```

`validationErrors` accepts a string or an array of strings per field, so Zod's output fits as-is. Run the same schema on the server to keep both sides in sync. The live example below uses a few lines of hand-written rules in place of Zod, with the same result shape.

Example `form/schema`: source in https://desyne.dev/docs/components/form.md

### Settings page

Several `FormSection`s with `layout="aside"` put each section's title and description in a left column on wide screens, a common layout for settings and account pages. `gap="lg"` adds room between sections, and `FormActions separator` closes the form with a hairline.

Example `form/settings`: source in https://desyne.dev/docs/components/form.md

### Inline

`layout="inline"` lines fields and buttons up in a row that wraps, aligned to the bottom edge so a button sits level with the input even when the field has a label. Good for newsletter sign-ups, search bars and table filters. Use `aria-label` when there's no visible label.

Example `form/inline`: source in https://desyne.dev/docs/components/form.md

### Submitting state

While a request runs, show `isPending` on the submit button. It keeps the button focusable, shows a spinner and announces the pending state, and ignores further presses so the form can't be sent twice. Make the fields `isReadOnly` rather than `isDisabled` so their values stay readable and are still submitted.

Example `form/submitting`: source in https://desyne.dev/docs/components/form.md

## Accessibility

* `Form` renders a native `<form>`, so <kbd>Enter</kbd> in a text field submits it and the browser's autofill works. Give each field a `name`.
* On submit, the first invalid field receives focus, and each field's error is linked to it with `aria-describedby` and announced.
* Server errors from `validationErrors` mark fields `aria-invalid` like any other error.
* `FormSection` is a `<fieldset>` whose `<legend>` names the group, so screen readers announce "Notifications, group" when focus enters it. The description is linked with `aria-describedby`.
* Status messages after submit ("Saved", "Sent") should live in an element with `role="status"` or `aria-live="polite"` so they're announced, as in the examples.
* Required fields show an asterisk and set `aria-required`. Say what the asterisk means near the top of long forms.

## Styling

### Data slots

| Slot                                   | Element                                                        |
| -------------------------------------- | -------------------------------------------------------------- |
| `data-slot="form"`                     | The `<form>`. Also has `data-layout="vertical"` or `"inline"`. |
| `data-slot="form-section"`             | The `<fieldset>`, with `data-layout="stacked"` or `"aside"`    |
| `data-slot="form-section-title"`       | The `<legend>`                                                 |
| `data-slot="form-section-description"` | The description `<p>`                                          |
| `data-slot="form-section-content"`     | The column that holds the fields                               |
| `data-slot="form-row"`                 | A `FormRow` grid                                               |
| `data-slot="form-actions"`             | The button row. Has `data-separator` when `separator` is set.  |

React Aria sets `data-invalid` on each field, not on the form. To style the whole form while it has errors, use `has-data-invalid:` on the form's `className`.

## API Reference

### Form

<TypeTable
  type="{
  layout: { type: '&#x22;vertical&#x22; | &#x22;inline&#x22;', default: '&#x22;vertical&#x22;', description: &#x22;Stack fields, or put them in a wrapping row aligned to the bottom.&#x22; },
  gap: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Space between children: 12px, 20px or 32px.&#x22; },
  validationBehavior: { type: '&#x22;aria&#x22; | &#x22;native&#x22;', default: '&#x22;aria&#x22;', description: &#x22;aria shows errors live and never blocks submit; native uses the browser's constraint validation and blocks submit.&#x22; },
  validationErrors: { type: &#x22;Record<string, string | string[]>&#x22;, description: &#x22;Errors keyed by field name, typically from the server. Cleared per field when the user edits it.&#x22; },
  onSubmit: { type: &#x22;(e: FormEvent<HTMLFormElement>) => void&#x22;, description: &#x22;Called on submit. Call e.preventDefault() to handle it in JavaScript.&#x22; },
  action: { type: &#x22;string | ((formData: FormData) => void | Promise<void>)&#x22;, description: &#x22;A URL, or a React form action (server action).&#x22; },
  onReset: { type: &#x22;(e: FormEvent<HTMLFormElement>) => void&#x22;, description: &#x22;Called when the form is reset.&#x22; },
  onInvalid: { type: &#x22;(e: FormEvent<HTMLFormElement>) => void&#x22;, description: &#x22;Called when native validation fails on submit.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the <form>.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Form`](https://react-aria.adobe.com/Form#api) and native `<form>` attributes such as `method`, `encType`, `autoComplete` and `noValidate`.

### FormSection

<TypeTable
  type="{
  title: { type: &#x22;ReactNode&#x22;, description: &#x22;Rendered as the <legend>; names the group.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text under the title, linked with aria-describedby.&#x22; },
  layout: { type: '&#x22;stacked&#x22; | &#x22;aside&#x22;', default: '&#x22;stacked&#x22;', description: &#x22;Title above the fields, or in a left column from the md breakpoint.&#x22; },
  disabled: { type: &#x22;boolean&#x22;, description: &#x22;Native fieldset disabling: every native control inside is disabled and left out of submission. Set isDisabled on fields too so they look disabled.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts native `<fieldset>` attributes.

### FormRow

<TypeTable
  type="{
  columns: { type: &#x22;2 | 3 | 4&#x22;, default: &#x22;2&#x22;, description: &#x22;Columns from the sm breakpoint (4 columns become 2 below lg).&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

### FormActions

<TypeTable
  type="{
  align: { type: '&#x22;start&#x22; | &#x22;end&#x22; | &#x22;between&#x22;', default: '&#x22;end&#x22;', description: &#x22;Horizontal alignment of the buttons.&#x22; },
  separator: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Adds a top border and padding.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

## Related

* [Text Field](/docs/components/text-field), [Select](/docs/components/select), [Checkbox](/docs/components/checkbox) — the fields that go inside.
* [Button](/docs/components/button) — `isPending` for the submit state.
* [Alert](/docs/components/alert) — form-level errors that don't belong to one field.

---

# Text Field

Source: https://desyne.dev/docs/components/text-field

> A single-line text input with a label, help text and validation. Supports icon and text adornments, every native input type, native and custom validation, server errors and form submission.

```tsx title="text-field/demo.tsx"
"use client";

import { TextField } from "@/components/ui/text-field";

export default function TextFieldDemo() {
  return (
    <TextField
      className="w-full max-w-xs"
      label="Email"
      type="email"
      placeholder="you@company.com"
      description="We'll send the invite here."
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/text-field
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { TextField } from "@/components/ui/text-field";
```

```tsx
<TextField label="Email" name="email" type="email" isRequired />
```

`TextField` renders the label, the input, the description and the error message, and wires them together for assistive technology. Pass `value` and `onChange` to control it, or `defaultValue` to leave it uncontrolled.

<Callout title="onChange receives a string">
  React Aria calls `onChange` with the new value, not a DOM event, so you can
  pass a state setter directly: `onChange={setName}`. Use `onInput` or
  `onKeyDown` if you need the raw event.
</Callout>

### When to use

* Text Field — short, free-form, single-line text: names, emails, URLs, codes.
* [Textarea](/docs/components/textarea) — multi-line text such as comments, bios or descriptions.
* [Number Field](/docs/components/number-field) — numbers that benefit from steppers, locale formatting and min/max constraints.
* [Search Field](/docs/components/search-field) — search queries, with a clear button and <kbd>Esc</kbd> to clear.
* [Combo Box](/docs/components/combobox) — free text with suggestions from a list.
* [Input OTP](/docs/components/input-otp) — one-time codes split into individual character slots.

## Anatomy

```tsx
<TextField>          {/* root: <div>, owns value, validation and state attributes */}
  <Label />          {/* from `label` */}
  <FieldGroup>       {/* the visible box: border, focus ring, invalid state */}
    <FieldAddon />   {/* from `prefix` */}
    <FieldInput />   {/* the native <input> */}
    <FieldAddon />   {/* from `suffix` */}
  </FieldGroup>
  <Description />    {/* from `description` */}
  <FieldError />     {/* shown only while invalid */}
</TextField>
```

| Part          | Renders                      | Notes                                                                                                                   |
| ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `TextField`   | `<div>`                      | Root. Carries `data-slot="text-field"`, the `group/field` class and all state attributes.                               |
| `Label`       | `<label>`                    | Rendered when `label` is set. Adds a red `*` when `isRequired`.                                                         |
| `FieldGroup`  | `<div role="presentation">`  | Draws the chrome (`fieldVariants`). Picks up `data-focus-within`, `data-hovered`, `data-invalid` and `data-disabled`.   |
| `FieldAddon`  | `<span>`                     | Wraps `prefix` and `suffix`. Muted, non-selectable, and sizes any SVG icon inside it.                                   |
| `FieldInput`  | `<input>`                    | Receives `type`, `name`, `placeholder`, `autoComplete`, `inputMode`, `maxLength`, `pattern` and every other input prop. |
| `Description` | `<span slot="description">`  | Rendered when `description` is set. Linked with `aria-describedby`.                                                     |
| `FieldError`  | `<span slot="errorMessage">` | Rendered only while the field is invalid. Shows `errorMessage` or the validation messages.                              |

## Examples

### Variants

`outline` for most forms, `filled` for dense settings pages and tinted surfaces, `underlined` for minimal or inline editing. The same variants apply to every field component.

Example `text-field/variants`: source in https://desyne.dev/docs/components/text-field.md

### Sizes

`sm` (28px), `md` (32px, default) and `lg` (40px) line up with the button sizes of the same name, so a field and a button sit flush in a row.

Example `text-field/sizes`: source in https://desyne.dev/docs/components/text-field.md

### Prefix and suffix

`prefix` and `suffix` accept icons, text or any element. They sit inside the field, so the whole box highlights on focus. Use text adornments for fixed parts of the value (a scheme, a domain, a currency) that the user shouldn't type.

Example `text-field/prefix-suffix`: source in https://desyne.dev/docs/components/text-field.md

### Password with visibility toggle

A React Aria `Button` in the `suffix` toggles `type` between `password` and `text`. Give it an `aria-label` that describes the action, and set `autoComplete` so password managers recognise the field.

Example `text-field/password`: source in https://desyne.dev/docs/components/text-field.md

### Input types and hints

`type`, `inputMode` and `autoComplete` pick the right mobile keyboard and let browsers autofill. Turn off `spellCheck` and `autoCorrect` for identifiers like repository names or usernames.

Example `text-field/input-types`: source in https://desyne.dev/docs/components/text-field.md

### Disabled and read only

`isDisabled` removes the field from the tab order and dims it. `isReadOnly` keeps it focusable and selectable, so users can still copy the value. Prefer read only for values users need but can't change.

Example `text-field/disabled`: source in https://desyne.dev/docs/components/text-field.md

### Controlled

`value` and `onChange` let you derive UI from the value as it's typed, here a URL slug.

Example `text-field/controlled`: source in https://desyne.dev/docs/components/text-field.md

### Required and native validation

`isRequired`, `type="email"`, `pattern`, `minLength` and `maxLength` use the browser's constraint validation. By default (`validationBehavior="native"`) the form won't submit while a field is invalid, and errors appear after the user submits.

Example `text-field/validation`: source in https://desyne.dev/docs/components/text-field.md

### Custom validation

`validate` receives the current value and returns an error string, an array of strings, or `null` / `true` when valid. With `validationBehavior="aria"` on the `Form` (or the field), errors show live as the user types and don't block submission.

Example `text-field/custom-validation`: source in https://desyne.dev/docs/components/text-field.md

### Server errors

Pass `validationErrors` to React Aria's `Form`, keyed by field `name`, to show errors returned by your API. Each error clears as soon as the user edits that field. For a single field, `isInvalid` with `errorMessage` does the same.

Example `text-field/server-errors`: source in https://desyne.dev/docs/components/text-field.md

### Form submission

Give the field a `name` and its value is included in `FormData`, exactly like a native `<input>`. `type="reset"` restores each field's `defaultValue`.

Example `text-field/form`: source in https://desyne.dev/docs/components/text-field.md

### Custom composition

When the props aren't enough, build the field from the parts in `field.tsx` inside React Aria's `TextField`. Here a label row with a plan hint and an inline action button. Add `group/field` to the root so the label reacts to the disabled and required states.

Example `text-field/composition`: source in https://desyne.dev/docs/components/text-field.md

## Recipes

### Copy to clipboard

A read-only field with a ghost icon button in the suffix. The value stays selectable, and the button confirms the copy.

Example `text-field/recipe-copy`: source in https://desyne.dev/docs/components/text-field.md

### Inline subscribe form

A label-less field (`aria-label`) next to its submit button, with a pending state and a confirmation.

Example `text-field/recipe-newsletter`: source in https://desyne.dev/docs/components/text-field.md

### Profile settings

A card form with a two-column grid, adornments, `autoComplete` hints and a footer with reset and submit.

Example `text-field/recipe-profile`: source in https://desyne.dev/docs/components/text-field.md

## Accessibility

* The label, description and error message are linked to the input with `aria-labelledby` and `aria-describedby`. Clicking the label focuses the input.
* Always provide a label: `label`, `aria-label`, or `aria-labelledby`. A `placeholder` is not a label.
* Invalid fields get `aria-invalid`, and the error text is announced as part of the description.
* The required asterisk is decorative (a CSS pseudo-element). Screen readers get `aria-required` (or native `required` with native validation) instead.
* Icon-only buttons in `prefix` or `suffix` need an `aria-label`. Icons that are purely decorative need nothing: lucide icons are `aria-hidden` by default.
* `isReadOnly` fields stay in the tab order; `isDisabled` fields don't.

### Keyboard

| Key              | Action                                                    |
| ---------------- | --------------------------------------------------------- |
| <kbd>Tab</kbd>   | Moves focus to the input, then to any focusable adornment |
| <kbd>Enter</kbd> | Submits the surrounding form                              |

## Styling

### Data attributes

On the `TextField` root. Children can react with `group-data-*/field:` variants, e.g. `group-data-invalid/field:text-destructive`.

| Attribute       | Present when                              |
| --------------- | ----------------------------------------- |
| `data-disabled` | `isDisabled` is true                      |
| `data-readonly` | `isReadOnly` is true                      |
| `data-required` | `isRequired` is true                      |
| `data-invalid`  | Validation failed, or `isInvalid` is true |

On the `FieldGroup` (the visible box):

| Attribute                        | Present when                          |
| -------------------------------- | ------------------------------------- |
| `data-hovered`                   | Hovered with a mouse or pen           |
| `data-focus-within`              | The input (or an adornment) has focus |
| `data-focus-visible`             | Focus inside came from the keyboard   |
| `data-invalid` / `data-disabled` | Mirrors the field state               |

The input itself exposes `data-focused`, `data-focus-visible`, `data-hovered`, `data-invalid` and `data-disabled`.

### Slots

| `data-slot`                           | Element                    |
| ------------------------------------- | -------------------------- |
| `text-field`                          | Root                       |
| `label`, `description`, `field-error` | Field text                 |
| `field-group`                         | Visible box                |
| `field-input`                         | `<input>`                  |
| `field-addon`                         | Prefix and suffix wrappers |

### Render props

`className` on `TextField` styles the root and also accepts a function of the field state:

```tsx
<TextField
  label="Email"
  className={({ isInvalid }) => (isInvalid ? "animate-shake" : "")}
/>
```

### Style helpers

`field.tsx` exports the building blocks and their styles, shared by every field component:

```tsx
import {
  bareInputStyles, // classes for an <input> inside a FieldGroup
  fieldVariants,   // tailwind-variants for the box: { variant, size }
  inputVariants,   // same look for a standalone <input>, keyed off data-focused
} from "@/components/ui/field";
```

## API Reference

### TextField

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text shown under the input.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message while invalid.&#x22; },
  placeholder: { type: &#x22;string&#x22;, description: &#x22;Hint shown while the input is empty. Not a substitute for a label.&#x22; },
  prefix: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon, text or element shown before the input.&#x22; },
  suffix: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon, text, button or element shown after the input.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  value: { type: &#x22;string&#x22;, description: &#x22;Controlled value.&#x22; },
  defaultValue: { type: &#x22;string&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called with the new value on every change.&#x22; },
  type: { type: '&#x22;text&#x22; | &#x22;search&#x22; | &#x22;url&#x22; | &#x22;tel&#x22; | &#x22;email&#x22; | &#x22;password&#x22; | (string & {})', default: '&#x22;text&#x22;', description: &#x22;Native input type.&#x22; },
  inputMode: { type: '&#x22;none&#x22; | &#x22;text&#x22; | &#x22;tel&#x22; | &#x22;url&#x22; | &#x22;email&#x22; | &#x22;numeric&#x22; | &#x22;decimal&#x22; | &#x22;search&#x22;', description: &#x22;Virtual keyboard hint for touch devices.&#x22; },
  autoComplete: { type: &#x22;string&#x22;, description: &#x22;Autofill hint, e.g. email, name, current-password, one-time-code.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to, when rendered outside it.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires a value before the form can submit.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the field and removes it from the tab order.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Makes the value unchangeable but still focusable and selectable.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state, e.g. for server errors.&#x22; },
  validate: { type: &#x22;(value: string) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error string (or array of strings) to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live without blocking. Inherits from a parent Form.&#x22; },
  minLength: { type: &#x22;number&#x22;, description: &#x22;Native minimum length constraint.&#x22; },
  maxLength: { type: &#x22;number&#x22;, description: &#x22;Maximum number of characters the input accepts.&#x22; },
  pattern: { type: &#x22;string&#x22;, description: &#x22;Native regex constraint the whole value must match.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, description: &#x22;Focuses the input on mount.&#x22; },
  autoCorrect: { type: &#x22;string&#x22;, description: 'Safari autocorrect, &#x22;on&#x22; or &#x22;off&#x22;.' },
  spellCheck: { type: &#x22;string&#x22;, description: 'Browser spell checking, &#x22;true&#x22; or &#x22;false&#x22;.' },
  enterKeyHint: { type: '&#x22;enter&#x22; | &#x22;done&#x22; | &#x22;go&#x22; | &#x22;next&#x22; | &#x22;previous&#x22; | &#x22;search&#x22; | &#x22;send&#x22;', description: &#x22;Label for the enter key on virtual keyboards.&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onBlur: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onKeyDown: { type: &#x22;(e: KeyboardEvent) => void&#x22; },
  className: { type: &#x22;string | ((state: TextFieldRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`TextField`](https://react-aria.adobe.com/TextField#api), including clipboard, composition and selection event handlers.

### Building blocks

Exported from `@/components/ui/field` and shared by every field component.

| Export        | Wraps                                       | Props                                                                                |
| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------ |
| `Label`       | React Aria `Label`                          | `LabelProps`                                                                         |
| `Description` | React Aria `Text` with `slot="description"` | `TextProps`                                                                          |
| `FieldError`  | React Aria `FieldError`                     | `FieldErrorProps`; `children` may be a function of the validation result             |
| `FieldGroup`  | React Aria `Group`                          | `GroupProps` plus `variant` and `size`                                               |
| `FieldInput`  | React Aria `Input`                          | `InputProps`; unstyled, for use inside `FieldGroup`                                  |
| `Input`       | React Aria `Input`                          | `InputProps` plus `variant` and `size`; a standalone styled input without adornments |
| `FieldAddon`  | `<span>`                                    | `ComponentProps<"span">`                                                             |

## Related

* [Textarea](/docs/components/textarea) — the multi-line version.
* [Number Field](/docs/components/number-field) — numeric input with steppers and formatting.
* [Search Field](/docs/components/search-field) — search input with a clear button.
* [Combo Box](/docs/components/combobox) — text input with a list of suggestions.
* [Select](/docs/components/select) — shares the same field variants and sizes.

---

# Textarea

Source: https://desyne.dev/docs/components/textarea

> A multi-line text input for comments, descriptions and messages. Comes as a complete field with label, help text, character count and validation, or as a bare styled textarea. Resizes vertically, stays fixed, or grows with its content.

```tsx title="textarea/demo.tsx"
"use client";

import { TextareaField } from "@/components/ui/textarea";

export default function TextareaDemo() {
  return (
    <TextareaField
      className="w-full max-w-sm"
      label="Feedback"
      placeholder="What could we do better?"
      description="Your feedback goes to the product team."
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/textarea
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { Textarea, TextareaField } from "@/components/ui/textarea";
```

```tsx
<TextareaField label="Description" name="description" placeholder="Describe the issue" />
```

The file exports two components:

* `TextareaField` — a React Aria `TextField` with a label, description, character count and error message around a `Textarea`. Use it in forms.
* `Textarea` — just the styled `<textarea>`. Use it when you lay out the label yourself, or inside a custom composer.

<Callout title="The two onChange signatures differ">
  `TextareaField` is a React Aria field, so `onChange` receives the new string:
  `onChange={setValue}`. A standalone `Textarea` is a plain textarea element,
  so `onChange` receives the event: `onChange={(e) => setValue(e.target.value)}`.
</Callout>

### When to use

* Textarea — free-form text that may span several lines: comments, bios, descriptions, messages.
* [Text Field](/docs/components/text-field) — short, single-line values such as names, emails or titles.
* [Search Field](/docs/components/search-field) — search queries.
* A rich-text editor — when users need formatting, mentions or embeds. A textarea holds plain text only.

## Anatomy

```tsx
<TextareaField>      {/* root: React Aria TextField, owns value and validation */}
  <Label />          {/* from `label` */}
  <Textarea />       {/* the native <textarea> */}
  <div>              {/* only when there is a description or a count */}
    <Description />  {/* from `description` */}
    <span />         {/* `value.length / maxLength` when `showCount` */}
  </div>
  <FieldError />     {/* shown only while invalid */}
</TextareaField>
```

| Part            | Renders                      | Notes                                                                                                                                                    |
| --------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TextareaField` | `<div>`                      | Root. Carries `data-slot="textarea-field"`, the `group/field` class and all state attributes.                                                            |
| `Label`         | `<label>`                    | Rendered when `label` is set. Adds a red `*` when `isRequired`.                                                                                          |
| `Textarea`      | `<textarea>`                 | The control itself, styled by `textareaVariants`. Carries `data-slot="textarea"`. Receives `placeholder`, `rows`, `variant` and `resize` from the field. |
| `Description`   | `<span slot="description">`  | Rendered when `description` is set. Linked with `aria-describedby`.                                                                                      |
| Count           | `<span>`                     | Rendered when `showCount` and `maxLength` are both set. Right-aligned, tabular numbers.                                                                  |
| `FieldError`    | `<span slot="errorMessage">` | Rendered only while the field is invalid.                                                                                                                |

## Examples

### Variants

`outline` for most forms, `filled` for dense layouts and tinted surfaces, `underlined` for minimal, inline editing. They match the variants of the other field components.

Example `textarea/variants`: source in https://desyne.dev/docs/components/textarea.md

### Resize behavior

`resize="vertical"` (default) lets users drag the corner. `none` keeps a fixed height and scrolls. `auto` grows the textarea with its content using CSS `field-sizing: content`; in browsers without support it falls back to a fixed height. Use `rows` to set the initial height; the minimum is 80px.

Example `textarea/resize`: source in https://desyne.dev/docs/components/textarea.md

### Character count

`showCount` shows `value.length / maxLength` under the field when `maxLength` is set. It works on controlled and uncontrolled fields: with `value` the count reads from it, otherwise the field tracks the length itself, starting from `defaultValue`. Your `onChange` is still called. `maxLength` also stops input at the limit.

Example `textarea/count`: source in https://desyne.dev/docs/components/textarea.md

### Disabled and read only

`isDisabled` dims the field and removes it from the tab order. `isReadOnly` keeps the text focusable and selectable, which suits quoting an original message.

Example `textarea/disabled`: source in https://desyne.dev/docs/components/textarea.md

### Required and native validation

`isRequired`, `minLength` and `maxLength` use the browser's constraint validation. With the default `validationBehavior="native"`, the form won't submit while the field is invalid and the browser's message appears on submit.

Example `textarea/validation`: source in https://desyne.dev/docs/components/textarea.md

### Custom validation

`validate` receives the current value and returns an error string, or `null` when valid. With `validationBehavior="aria"` on the `Form`, errors appear live as the user types.

Example `textarea/custom-validation`: source in https://desyne.dev/docs/components/textarea.md

### Form submission

Give the field a `name` and its value is included in `FormData`, line breaks and all.

Example `textarea/form`: source in https://desyne.dev/docs/components/textarea.md

### Standalone

`Textarea` on its own is a styled `<textarea>` with the same `variant` and `resize` options. It has no label, so pass `aria-label` or `aria-labelledby`.

Example `textarea/standalone`: source in https://desyne.dev/docs/components/textarea.md

### Custom composition

Build your own field from React Aria's `TextField`, the `Label`, `Description` and `FieldError` parts in `field.tsx`, and `Textarea`. Here the description sits above the input and the label row carries an "Optional" hint. Add `group/field` to the root so the label reacts to the disabled and required states.

Example `textarea/composition`: source in https://desyne.dev/docs/components/textarea.md

## Recipes

### Comment composer

A borderless `Textarea` inside a bordered box with a toolbar, growing with its content. <kbd>⌘</kbd> + <kbd>Enter</kbd> posts the comment via `onKeyDown`.

Example `textarea/recipe-comment`: source in https://desyne.dev/docs/components/textarea.md

### Feedback form

A [`Select`](/docs/components/select) for the topic, a counted `TextareaField`, a pending submit button and a success state.

Example `textarea/recipe-feedback`: source in https://desyne.dev/docs/components/textarea.md

## Accessibility

* `TextareaField` links the label, description and error message to the textarea with `aria-labelledby` and `aria-describedby`.
* A standalone `Textarea` needs `aria-label` or `aria-labelledby`. A `placeholder` is not a label.
* Invalid fields get `aria-invalid`, and the error text is announced.
* The character count is plain text and isn't linked to the textarea. Mention the limit in `description` if screen-reader users need it up front.
* <kbd>Enter</kbd> inserts a new line. If you add a submit shortcut, use a modifier (<kbd>⌘</kbd> / <kbd>Ctrl</kbd> + <kbd>Enter</kbd>) and show it visibly, as in the comment recipe.

### Keyboard

| Key              | Action                                   |
| ---------------- | ---------------------------------------- |
| <kbd>Tab</kbd>   | Moves focus into and out of the textarea |
| <kbd>Enter</kbd> | Inserts a new line                       |

## Styling

### Data attributes

On the `TextareaField` root. Children can react with `group-data-*/field:` variants.

| Attribute       | Present when                              |
| --------------- | ----------------------------------------- |
| `data-disabled` | `isDisabled` is true                      |
| `data-readonly` | `isReadOnly` is true                      |
| `data-required` | `isRequired` is true                      |
| `data-invalid`  | Validation failed, or `isInvalid` is true |

On the `Textarea` element (the variants style these):

| Attribute            | Present when                 |
| -------------------- | ---------------------------- |
| `data-hovered`       | Hovered with a mouse or pen  |
| `data-focused`       | The textarea has focus       |
| `data-focus-visible` | Focus came from the keyboard |
| `data-invalid`       | The field is invalid         |
| `data-disabled`      | The field is disabled        |

### Slots

| `data-slot`                           | Element                 |
| ------------------------------------- | ----------------------- |
| `textarea-field`                      | Root of `TextareaField` |
| `textarea`                            | `<textarea>`            |
| `label`, `description`, `field-error` | Field text              |

### `textareaVariants`

The `tailwind-variants` function behind `Textarea`, with `variant` (`outline`, `filled`, `underlined`) and `resize` (`none`, `vertical`, `auto`). Use it to style a textarea from another library the same way.

```tsx
import { textareaVariants } from "@/components/ui/textarea";

<textarea className={textareaVariants({ variant: "filled", resize: "none" })} />;
```

`className` on `TextareaField` styles the root; on `Textarea` it styles the textarea and also accepts a function of its render state (`isFocused`, `isHovered`, `isInvalid`, `isDisabled`).

## API Reference

### TextareaField

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text shown under the textarea.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message while invalid.&#x22; },
  placeholder: { type: &#x22;string&#x22;, description: &#x22;Hint shown while the textarea is empty.&#x22; },
  rows: { type: &#x22;number&#x22;, description: &#x22;Initial visible rows. The textarea is at least 80px tall.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  resize: { type: '&#x22;none&#x22; | &#x22;vertical&#x22; | &#x22;auto&#x22;', default: '&#x22;vertical&#x22;', description: &#x22;auto grows with the content via CSS field-sizing.&#x22; },
  showCount: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shows value.length / maxLength. Requires maxLength; works controlled or uncontrolled.&#x22; },
  maxLength: { type: &#x22;number&#x22;, description: &#x22;Maximum number of characters. Also enables the count.&#x22; },
  minLength: { type: &#x22;number&#x22;, description: &#x22;Native minimum length constraint.&#x22; },
  value: { type: &#x22;string&#x22;, description: &#x22;Controlled value.&#x22; },
  defaultValue: { type: &#x22;string&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called with the new value on every change.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state, e.g. for server errors.&#x22; },
  validate: { type: &#x22;(value: string) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live. Inherits from a parent Form.&#x22; },
  autoComplete: { type: &#x22;string&#x22; },
  spellCheck: { type: &#x22;string&#x22;, description: 'Browser spell checking, &#x22;true&#x22; or &#x22;false&#x22;.' },
  enterKeyHint: { type: '&#x22;enter&#x22; | &#x22;done&#x22; | &#x22;go&#x22; | &#x22;next&#x22; | &#x22;previous&#x22; | &#x22;search&#x22; | &#x22;send&#x22;' },
  autoFocus: { type: &#x22;boolean&#x22; },
  onKeyDown: { type: &#x22;(e: KeyboardEvent) => void&#x22;, description: &#x22;Use for shortcuts such as Cmd + Enter to submit.&#x22; },
  className: { type: &#x22;string | ((state: TextFieldRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`TextField`](https://react-aria.adobe.com/TextField#api).

### Textarea

<TypeTable
  type="{
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  resize: { type: '&#x22;none&#x22; | &#x22;vertical&#x22; | &#x22;auto&#x22;', default: '&#x22;vertical&#x22;' },
  rows: { type: &#x22;number&#x22; },
  value: { type: &#x22;string&#x22;, description: &#x22;Controlled value (standalone use).&#x22; },
  defaultValue: { type: &#x22;string&#x22; },
  onChange: { type: &#x22;(e: ChangeEvent<HTMLTextAreaElement>) => void&#x22;, description: &#x22;Native change event (standalone use). Inside a TextField, use the field's onChange instead.&#x22; },
  className: { type: &#x22;string | ((state: InputRenderProps) => string)&#x22; },
}"
/>

Accepts every native `<textarea>` attribute, plus the props of React Aria's [`TextArea`](https://react-aria.adobe.com/TextField#textarea). Inside a `TextField`, the field supplies the value, id and ARIA attributes.

## Related

* [Text Field](/docs/components/text-field) — the single-line version, and the shared field building blocks.
* [Search Field](/docs/components/search-field) — for search queries.
* [Select](/docs/components/select) — shares the same field variants.

---

# Number Field

Source: https://desyne.dev/docs/components/number-field

> A numeric input with increment and decrement steppers. Formats and parses numbers in the user's locale, supports currency, percent and unit formatting, min/max/step constraints, keyboard and scroll-wheel stepping, validation and form submission.

```tsx title="number-field/demo.tsx"
"use client";

import { NumberField } from "@/components/ui/number-field";

export default function NumberFieldDemo() {
  return (
    <NumberField
      className="w-full max-w-48"
      label="Seats"
      defaultValue={5}
      minValue={1}
      maxValue={50}
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/number-field
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { NumberField } from "@/components/ui/number-field";
```

```tsx
<NumberField label="Quantity" name="quantity" defaultValue={1} minValue={0} />
```

The value is always a `number`. The field formats it for display with `formatOptions` and the user's locale, parses what the user types, and on blur clamps it to `minValue` / `maxValue` and snaps it to `step`.

<Callout title="An empty field is NaN">
  When the user clears the input, `onChange` receives `NaN`, not `0` or
  `null`. Check with `Number.isNaN(value)` before doing arithmetic, and use
  `isRequired` if an empty value isn't allowed.
</Callout>

### When to use

* Number Field — quantities, prices, percentages, measurements: any value that is really a number and benefits from steppers, formatting or a range.
* [Slider](/docs/components/slider) — picking an approximate value in a range, where the exact number matters less than its position.
* [Text Field](/docs/components/text-field) — number-like strings that aren't quantities: phone numbers, postal codes, card numbers, IDs. Use `inputMode="numeric"` there.
* [Input OTP](/docs/components/input-otp) — one-time verification codes.

## Anatomy

```tsx
<NumberField>              {/* root: <div>, owns the number value and validation */}
  <Label />                {/* from `label` */}
  <FieldGroup>             {/* role="group": the visible box */}
    <Button slot="decrement" />  {/* stepper="split" only */}
    <FieldInput />               {/* the text <input> */}
    <Button slot="increment" />  {/* stepper="split" only */}
    <div>                        {/* stepper="stacked" only */}
      <Button slot="increment" />
      <Button slot="decrement" />
    </div>
  </FieldGroup>
  <Description />          {/* from `description` */}
  <FieldError />           {/* shown only while invalid */}
</NumberField>
```

| Part                  | Renders                      | Notes                                                                                                                                                    |
| --------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NumberField`         | `<div>`                      | Root. Carries `data-slot="number-field"`, the `group/field` class and all state attributes.                                                              |
| `Label`               | `<label>`                    | Rendered when `label` is set.                                                                                                                            |
| `FieldGroup`          | `<div role="group">`         | The visible box. Groups the input and steppers for assistive technology.                                                                                 |
| `FieldInput`          | `<input type="text">`        | Shows the formatted value. `inputMode` is chosen from `minValue` and the format so the right mobile keyboard appears.                                    |
| Increment / decrement | `<button>`                   | Chevrons (`stacked`) or plus/minus (`split`). Labelled "Increase …" / "Decrease …", excluded from the tab order, disabled at the bounds. Hold to repeat. |
| `Description`         | `<span slot="description">`  | Rendered when `description` is set.                                                                                                                      |
| `FieldError`          | `<span slot="errorMessage">` | Rendered only while invalid.                                                                                                                             |
| Hidden `<input>`      | `<input type="hidden">`      | Rendered when `name` is set. Submits the raw number, not the formatted text.                                                                             |

## Examples

### Variants

`outline` (default), `filled` for dense or tinted surfaces, and `underlined` for minimal forms. The same variants apply to every field component.

Example `number-field/variants`: source in https://desyne.dev/docs/components/number-field.md

### Sizes

`sm` (28px), `md` (32px, default) and `lg` (40px), matching the buttons and other fields.

Example `number-field/sizes`: source in https://desyne.dev/docs/components/number-field.md

### Stepper layouts

`stepper="stacked"` (default) puts compact chevrons on the right. `split` puts larger − and + buttons on either side, which suits touch and quantity pickers. `none` hides the buttons; the arrow keys and scroll wheel still work.

Example `number-field/steppers`: source in https://desyne.dev/docs/components/number-field.md

### Formatting

`formatOptions` takes any `Intl.NumberFormat` option: currency, percent, units, fraction digits, sign display, grouping. Users can type in their locale's format, including the currency symbol or percent sign. Percent values are fractions: `0.15` displays as 15%.

Example `number-field/formatting`: source in https://desyne.dev/docs/components/number-field.md

### Range and step

`minValue` and `maxValue` bound the value; the steppers disable at each end. `step` sets the increment, and typed values snap to the nearest step (counted from `minValue`) on blur. Fractional steps work with any format.

Example `number-field/range`: source in https://desyne.dev/docs/components/number-field.md

### Disabled and read only

`isDisabled` disables the input and steppers. `isReadOnly` keeps the formatted value focusable and selectable but blocks edits and stepping.

Example `number-field/disabled`: source in https://desyne.dev/docs/components/number-field.md

### Controlled

`value` and `onChange` let you derive UI from the number, like a live total. `onChange` fires when the value is committed (on blur, <kbd>Enter</kbd> or a step), not on every keystroke.

Example `number-field/controlled`: source in https://desyne.dev/docs/components/number-field.md

### Required and range validation

By default an out-of-range value is clamped on blur. Set `commitBehavior="validate"` to keep what the user typed and show a range error instead, so they notice the limit. With native validation, the form won't submit until the field is valid.

Example `number-field/validation`: source in https://desyne.dev/docs/components/number-field.md

### Custom validation

`validate` receives the parsed number (`NaN` when empty) and returns an error string or `null`. With `validationBehavior="aria"` on the `Form`, errors show live.

Example `number-field/custom-validation`: source in https://desyne.dev/docs/components/number-field.md

### Form submission

Set `name` and the raw number is submitted through a hidden input: `1500`, not `€1,500.00`, and `0.1`, not `10%`. An empty field submits an empty string.

Example `number-field/form`: source in https://desyne.dev/docs/components/number-field.md

## Recipes

### Cart quantities

Small `split` steppers in a line-item list, each with an `aria-label` that names the product, driving a live subtotal.

Example `number-field/recipe-cart`: source in https://desyne.dev/docs/components/number-field.md

### Resource limits

A settings list where each field is labelled by its row title via `aria-labelledby`, with unit formatting and per-row ranges.

Example `number-field/recipe-limits`: source in https://desyne.dev/docs/components/number-field.md

## Accessibility

* The input is a text field with `aria-roledescription="number field"`, so screen readers announce it as a number field along with its formatted value.
* The input and steppers are wrapped in a `role="group"` labelled by the field label.
* Stepper buttons are named "Increase Seats" / "Decrease Seats" from the label (override with `incrementAriaLabel` / `decrementAriaLabel`). They're skipped in the tab order because the arrow keys do the same job.
* Values are formatted and parsed with the user's locale, including their decimal and grouping separators and numbering system.
* `inputMode` is set automatically (`numeric`, `decimal` or `text`) so mobile keyboards include a minus sign or decimal point only when needed.
* The scroll wheel steps the value only while the field has focus. Disable it with `isWheelDisabled` in scrollable layouts.

### Keyboard

| Key                                       | Action                                                  |
| ----------------------------------------- | ------------------------------------------------------- |
| <kbd>↑</kbd> / <kbd>↓</kbd>               | Increments / decrements by `step`                       |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | Increments / decrements by `step`                       |
| <kbd>Home</kbd> / <kbd>End</kbd>          | Sets the value to `minValue` / `maxValue`, when set     |
| <kbd>Enter</kbd>                          | Commits the typed value (parse, clamp, snap and format) |

## Styling

### Data attributes

On the `NumberField` root. Children can react with `group-data-*/field:` variants.

| Attribute       | Present when                              |
| --------------- | ----------------------------------------- |
| `data-disabled` | `isDisabled` is true                      |
| `data-readonly` | `isReadOnly` is true                      |
| `data-required` | `isRequired` is true                      |
| `data-invalid`  | Validation failed, or `isInvalid` is true |

On the `FieldGroup`: `data-hovered`, `data-focus-within`, `data-focus-visible`, `data-invalid` and `data-disabled`. On each stepper button: `data-hovered`, `data-pressed`, `data-disabled` (at a bound) and `data-focus-visible`.

### Slots

| `data-slot`                           | Element     |
| ------------------------------------- | ----------- |
| `number-field`                        | Root        |
| `label`, `description`, `field-error` | Field text  |
| `field-group`                         | Visible box |
| `field-input`                         | `<input>`   |

The input uses `tabular-nums` so digits don't shift while stepping. The box styles come from `fieldVariants` in `field.tsx`; see [Text Field](/docs/components/text-field#style-helpers).

### Render props

`className` also accepts a function of the field state, which includes the live `state` (`numberValue`, `canIncrement`, `canDecrement`):

```tsx
<NumberField
  label="Balance"
  className={({ state }) => (state.numberValue < 0 ? "text-destructive" : "")}
/>
```

## API Reference

### NumberField

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text shown under the input.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message while invalid.&#x22; },
  placeholder: { type: &#x22;string&#x22;, description: &#x22;Shown while the input is empty.&#x22; },
  stepper: { type: '&#x22;stacked&#x22; | &#x22;split&#x22; | &#x22;none&#x22;', default: '&#x22;stacked&#x22;', description: &#x22;Layout of the increment and decrement buttons.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  value: { type: &#x22;number&#x22;, description: &#x22;Controlled value. NaN means empty.&#x22; },
  defaultValue: { type: &#x22;number&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: number) => void&#x22;, description: &#x22;Called when the value is committed: on blur, Enter or a step.&#x22; },
  minValue: { type: &#x22;number&#x22;, description: &#x22;Smallest allowed value. Also enables Home.&#x22; },
  maxValue: { type: &#x22;number&#x22;, description: &#x22;Largest allowed value. Also enables End.&#x22; },
  step: { type: &#x22;number&#x22;, default: &#x22;1&#x22;, description: &#x22;Increment for steppers and arrow keys. Typed values snap to it.&#x22; },
  formatOptions: { type: &#x22;Intl.NumberFormatOptions&#x22;, description: &#x22;Display format: currency, percent, unit, fraction digits and more. Also limits which characters can be typed.&#x22; },
  commitBehavior: { type: '&#x22;snap&#x22; | &#x22;validate&#x22;', default: '&#x22;snap&#x22;', description: &#x22;snap clamps and rounds on blur; validate keeps the typed value and reports range and step errors.&#x22; },
  isWheelDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Stops the scroll wheel from changing the value while focused.&#x22; },
  incrementAriaLabel: { type: &#x22;string&#x22;, description: 'Accessible name for the increment button. Defaults to &#x22;Increase&#x22; plus the label.' },
  decrementAriaLabel: { type: &#x22;string&#x22;, description: 'Accessible name for the decrement button. Defaults to &#x22;Decrease&#x22; plus the label.' },
  name: { type: &#x22;string&#x22;, description: &#x22;Submits the raw number through a hidden input.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state, e.g. for server errors.&#x22; },
  validate: { type: &#x22;(value: number) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live. Inherits from a parent Form.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onBlur: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onKeyDown: { type: &#x22;(e: KeyboardEvent) => void&#x22; },
  className: { type: &#x22;string | ((state: NumberFieldRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`NumberField`](https://react-aria.adobe.com/NumberField#api).

## Related

* [Slider](/docs/components/slider) — for approximate values in a range.
* [Text Field](/docs/components/text-field) — for number-like strings, and the shared field building blocks.
* [Select](/docs/components/select) — shares the same field variants and sizes.

---

# Search Field

Source: https://desyne.dev/docs/components/search-field

> A text input for search queries, with a search icon, a clear button, Escape to clear and an optional keyboard shortcut hint. Works for live filtering, submit-on-Enter, async search and native search forms.

```tsx title="search-field/demo.tsx"
"use client";

import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldDemo() {
  return (
    <SearchField
      aria-label="Search"
      className="w-full max-w-xs"
      shortcut="⌘K"
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/search-field
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { SearchField } from "@/components/ui/search-field";
```

```tsx
<SearchField aria-label="Search" onSubmit={(query) => search(query)} />
```

Use `value` and `onChange` to filter as the user types, or `onSubmit` to run the search when they press <kbd>Enter</kbd>. The clear button and <kbd>Esc</kbd> reset the value and call `onClear`.

<Callout title="onSubmit replaces form submission">
  When `onSubmit` is set, <kbd>Enter</kbd> calls it and does not submit a
  surrounding `<form>`. Leave `onSubmit` off (and give the field a `name`) when
  you want <kbd>Enter</kbd> to submit the form natively.
</Callout>

### When to use

* Search Field — a query that filters or searches content elsewhere on the page or site.
* [Combo Box](/docs/components/combobox) — the result is picking one option from a list shown under the input.
* [Command Palette](/docs/components/command-palette) — a global, keyboard-first launcher for navigation and actions.
* [Text Field](/docs/components/text-field) — ordinary text entry that isn't a query.

## Anatomy

```tsx
<SearchField>          {/* root: <div>, owns the query and state attributes */}
  <Label />            {/* from `label` */}
  <FieldGroup>         {/* the visible box */}
    <SearchIcon />     {/* decorative */}
    <FieldInput />     {/* <input type="search"> */}
    <Keyboard />       {/* from `shortcut`, only while empty */}
    <Button />         {/* clear button, only while not empty */}
  </FieldGroup>
  <Description />      {/* from `description` */}
  <FieldError />       {/* shown only while invalid */}
</SearchField>
```

| Part          | Renders                      | Notes                                                                                                                                                                 |
| ------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SearchField` | `<div>`                      | Root. Carries `data-slot="search-field"`, the `group/field` class and `data-empty` while the query is empty.                                                          |
| `Label`       | `<label>`                    | Rendered when `label` is set.                                                                                                                                         |
| `FieldGroup`  | `<div>`                      | The visible box, styled by `fieldVariants`.                                                                                                                           |
| Search icon   | `<svg>`                      | Decorative (`aria-hidden`).                                                                                                                                           |
| `FieldInput`  | `<input type="search">`      | The native input. The browser's own cancel button is hidden in favour of the clear button.                                                                            |
| Shortcut      | `<kbd>`                      | Rendered when `shortcut` is set, visible only while the field is empty. It's a hint; you bind the key.                                                                |
| Clear button  | `<button>`                   | Labelled "Clear search", skipped in the tab order, hidden while empty. React Aria wires it through context, so don't place other React Aria buttons inside the field. |
| `Description` | `<span slot="description">`  | Rendered when `description` is set.                                                                                                                                   |
| `FieldError`  | `<span slot="errorMessage">` | Rendered only while invalid.                                                                                                                                          |

## Examples

### Variants

`outline` (default), `filled` for toolbars, headers and tinted surfaces, and `underlined` for minimal layouts.

Example `search-field/variants`: source in https://desyne.dev/docs/components/search-field.md

### Sizes

`sm` (28px) suits toolbars and table headers, `md` (32px) is the default, `lg` (40px) suits hero and landing-page search.

Example `search-field/sizes`: source in https://desyne.dev/docs/components/search-field.md

### With label and description

Most search fields rely on `aria-label`, but a visible `label` helps in forms and filter panels. The default placeholder is "Search…".

Example `search-field/with-label`: source in https://desyne.dev/docs/components/search-field.md

### Keyboard shortcut

`shortcut` shows a hint while the field is empty. Binding the key is up to you: listen on `window` and focus the input. The root doesn't expose the input, so reach it through a wrapper ref.

Example `search-field/shortcut`: source in https://desyne.dev/docs/components/search-field.md

### Submit and clear

`onSubmit` runs on <kbd>Enter</kbd> with the current query, and `onClear` runs when the clear button or <kbd>Esc</kbd> empties the field. Set `enterKeyHint="search"` to label the enter key on mobile keyboards.

Example `search-field/submit`: source in https://desyne.dev/docs/components/search-field.md

### Live filtering

Control the value with `value` and `onChange` to filter a list as the user types. React Aria's `useFilter` gives you locale-aware `contains`, `startsWith` and `endsWith` matchers that ignore case and accents with `sensitivity: "base"`. Announce the result count with an `aria-live` region.

Example `search-field/controlled`: source in https://desyne.dev/docs/components/search-field.md

### Async search

Fetch results in an effect keyed on the query and abort stale requests, so fast typing never shows out-of-order results. Show a [`Spinner`](/docs/components/spinner) while loading and an empty state when nothing matches.

Example `search-field/async`: source in https://desyne.dev/docs/components/search-field.md

### Disabled and read only

`isDisabled` dims the field and disables the clear button. `isReadOnly` keeps a saved query visible and selectable, and also disables clearing.

Example `search-field/disabled`: source in https://desyne.dev/docs/components/search-field.md

### Search form

Without `onSubmit`, <kbd>Enter</kbd> submits the surrounding form natively and the query is sent under its `name`, like a classic `?q=` search. `isRequired` and `minLength` use native validation. Give the form `role="search"` so it's exposed as a search landmark.

Example `search-field/form`: source in https://desyne.dev/docs/components/search-field.md

## Recipes

### App header

A small `filled` search in a top bar, focused with <kbd>/</kbd> from anywhere on the page, next to icon actions.

Example `search-field/recipe-header`: source in https://desyne.dev/docs/components/search-field.md

### Filterable member list

A search in a card header filtering a list by name and email, with an empty state that clears the query.

Example `search-field/recipe-members`: source in https://desyne.dev/docs/components/search-field.md

## Accessibility

* The input has `type="search"`, so assistive technology announces it as a search field.
* Always provide a label: `label`, `aria-label`, or `aria-labelledby`. The search icon is decorative.
* The clear button is labelled "Clear search" (localized). It's skipped in the tab order because <kbd>Esc</kbd> does the same thing, and pressing it keeps focus in the input so the mobile keyboard stays open.
* The shortcut hint is visual only. If you bind a global shortcut, avoid keys users type into other inputs; the header recipe ignores <kbd>/</kbd> while an input is focused.
* Wrap search areas in `role="search"` (on a `<form>` or a `<div>`) to create a search landmark.
* For live results, announce counts or "no results" with an `aria-live="polite"` region.

### Keyboard

| Key              | Action                                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| <kbd>Enter</kbd> | Calls `onSubmit`, or submits the surrounding form when there's no `onSubmit`                                    |
| <kbd>Esc</kbd>   | Clears the field and calls `onClear`. When already empty, the key passes through, for example to close a dialog |

## Styling

### Data attributes

On the `SearchField` root. Children can react with `group-data-*/field:` variants; the component itself uses `group-data-empty/field:` to swap the shortcut hint and the clear button.

| Attribute       | Present when                              |
| --------------- | ----------------------------------------- |
| `data-empty`    | The query is empty                        |
| `data-disabled` | `isDisabled` is true                      |
| `data-readonly` | `isReadOnly` is true                      |
| `data-required` | `isRequired` is true                      |
| `data-invalid`  | Validation failed, or `isInvalid` is true |

On the `FieldGroup`: `data-hovered`, `data-focus-within`, `data-focus-visible`, `data-invalid` and `data-disabled`.

### Slots

| `data-slot`                           | Element     |
| ------------------------------------- | ----------- |
| `search-field`                        | Root        |
| `label`, `description`, `field-error` | Field text  |
| `field-group`                         | Visible box |
| `field-input`                         | `<input>`   |

The box comes from `fieldVariants` in `field.tsx`; see [Text Field](/docs/components/text-field#style-helpers). `className` also accepts a function of the render state (`isEmpty`, `isDisabled`, `isInvalid`, `isReadOnly`, `isRequired`, `state`).

## API Reference

### SearchField

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text shown under the input.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message while invalid.&#x22; },
  placeholder: { type: &#x22;string&#x22;, default: '&#x22;Search…&#x22;' },
  shortcut: { type: &#x22;string&#x22;, description: 'Keyboard hint shown while empty, e.g. &#x22;⌘K&#x22; or &#x22;/&#x22;. Binding the key is up to you.' },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  value: { type: &#x22;string&#x22;, description: &#x22;Controlled query.&#x22; },
  defaultValue: { type: &#x22;string&#x22;, description: &#x22;Uncontrolled initial query.&#x22; },
  onChange: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called with the new query on every change.&#x22; },
  onSubmit: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called on Enter. Prevents the surrounding form from submitting.&#x22; },
  onClear: { type: &#x22;() => void&#x22;, description: &#x22;Called when the clear button or Escape empties the field.&#x22; },
  type: { type: '&#x22;text&#x22; | &#x22;search&#x22; | &#x22;url&#x22; | &#x22;tel&#x22; | &#x22;email&#x22; | &#x22;password&#x22; | (string & {})', default: '&#x22;search&#x22;' },
  enterKeyHint: { type: '&#x22;enter&#x22; | &#x22;done&#x22; | &#x22;go&#x22; | &#x22;next&#x22; | &#x22;previous&#x22; | &#x22;search&#x22; | &#x22;send&#x22;', description: &#x22;Label for the enter key on virtual keyboards.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  autoComplete: { type: &#x22;string&#x22; },
  minLength: { type: &#x22;number&#x22;, description: &#x22;Native minimum length constraint.&#x22; },
  maxLength: { type: &#x22;number&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the input and the clear button.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Keeps the query selectable; disables editing and clearing.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22; },
  validate: { type: &#x22;(value: string) => ValidationError | true | null | undefined&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;Inherits from a parent Form.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onBlur: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onKeyDown: { type: &#x22;(e: KeyboardEvent) => void&#x22; },
  className: { type: &#x22;string | ((state: SearchFieldRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`SearchField`](https://react-aria.adobe.com/SearchField#api).

## Related

* [Combo Box](/docs/components/combobox) — search that ends in choosing an option.
* [Command Palette](/docs/components/command-palette) — a global search and command launcher.
* [Text Field](/docs/components/text-field) — the shared field building blocks.
* [Kbd](/docs/components/kbd) — for showing shortcuts elsewhere.

---

# Select

Source: https://desyne.dev/docs/components/select

> Pick a single option from a collapsible list. Supports icons, avatars, descriptions, sections, typeahead, form submission and validation.

```tsx title="select/demo.tsx"
"use client";

import { Select, SelectItem } from "@/components/ui/select";

export default function SelectDemo() {
  return (
    <Select
      className="w-full max-w-56"
      label="Region"
      placeholder="Select a region"
      defaultSelectedKey="us-east"
    >
      <SelectItem id="us-east">US East (Virginia)</SelectItem>
      <SelectItem id="us-west">US West (Oregon)</SelectItem>
      <SelectItem id="eu-central">EU Central (Frankfurt)</SelectItem>
      <SelectItem id="ap-south">Asia Pacific (Mumbai)</SelectItem>
    </Select>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/select
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  Select,
  SelectItem,
  SelectItemDescription,
  SelectItemLabel,
  SelectSection,
} from "@/components/ui/select";
```

```tsx
<Select label="Role" placeholder="Select a role">
  <SelectItem id="admin">Admin</SelectItem>
  <SelectItem id="member">Member</SelectItem>
  <SelectItem id="viewer">Viewer</SelectItem>
</Select>
```

### When to use

* Select — one choice from roughly 5–50 known options, where the options don't need to be visible all the time.
* [Radio Group](/docs/components/radio-group) — fewer than \~5 options that benefit from being visible side by side.
* [Combo Box](/docs/components/combobox) — long lists users will search, or when free-form input is allowed.
* [Menu](/docs/components/menu) — a list of actions, not a value.

## Anatomy

```tsx
<Select>                         {/* field: label, trigger, description, error */}
  <SelectSection title="…">      {/* optional group with a heading */}
    <SelectItem id="…">          {/* option */}
      <Icon />
      <SelectItemLabel />        {/* shown in the trigger */}
      <SelectItemDescription />  {/* shown only in the list */}
    </SelectItem>
  </SelectSection>
</Select>
```

| Part                    | Renders                        | Notes                                                                          |
| ----------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
| `Select`                | `<div>` + `<button>` + popover | Wraps label, trigger, description, error message and the listbox popover.      |
| Trigger                 | `<button>`                     | Shows the selected item (or placeholder), `prefix` and a chevron.              |
| `SelectItem`            | `role="option"`                | An option. Needs a unique `id`, and `textValue` if children aren't plain text. |
| `SelectItemLabel`       | `<span slot="label">`          | Primary text of a rich item; the only part rendered in the trigger.            |
| `SelectItemDescription` | `<span slot="description">`    | Secondary text; hidden in the trigger.                                         |
| `SelectSection`         | `role="group"`                 | Groups options under an optional `title`.                                      |
| Hidden `<select>`       | `<select>`                     | Rendered for native form submission and browser autofill when `name` is set.   |

## Examples

### Variants

`outline` (default), `filled` for dense or tinted surfaces, and `underlined` for minimal, inline forms. The same variants apply to every field component.

Example `select/variants`: source in https://desyne.dev/docs/components/select.md

### Sizes

Example `select/sizes`: source in https://desyne.dev/docs/components/select.md

### Dynamic items

Pass `items` and a render function instead of static children. Each item needs an `id` (or `key`) property; React Aria only re-renders items that changed.

Example `select/dynamic`: source in https://desyne.dev/docs/components/select.md

### Rich items

Compose icons with `SelectItemLabel` and `SelectItemDescription`. The trigger shows only the label, so the closed select stays compact. Set `textValue` for typeahead.

Example `select/rich-items`: source in https://desyne.dev/docs/components/select.md

### With avatars

Any element works as leading content. Here an [`Avatar`](/docs/components/avatar) makes people easier to scan.

Example `select/avatars`: source in https://desyne.dev/docs/components/select.md

### Sections and prefix

`SelectSection` groups options under a heading. `prefix` adds an icon to the trigger.

Example `select/sections`: source in https://desyne.dev/docs/components/select.md

### Long lists and typeahead

The list scrolls within the available viewport height. With the trigger focused, type a few letters to jump to the first matching option.

Example `select/long-list`: source in https://desyne.dev/docs/components/select.md

### Controlled

Use `selectedKey` and `onSelectionChange` to own the value. Set it to `null` to clear the selection and show the placeholder again.

Example `select/controlled`: source in https://desyne.dev/docs/components/select.md

### Disabled

`isDisabled` disables the whole field; `disabledKeys` disables specific options while keeping them visible. Use `description` to explain why.

Example `select/disabled`: source in https://desyne.dev/docs/components/select.md

### Required and validation

`isRequired` blocks form submission until an option is chosen and shows the browser's message. `disabledKeys` keeps unavailable options from being selected.

Example `select/validation`: source in https://desyne.dev/docs/components/select.md

### Custom validation

`validate` returns an error string (or `null`). With `validationBehavior="aria"` on the form, errors show live as the value changes instead of on submit.

Example `select/custom-validation`: source in https://desyne.dev/docs/components/select.md

### Form submission

Give the select a `name` and its value is included in `FormData`, exactly like a native `<select>`.

Example `select/form`: source in https://desyne.dev/docs/components/select.md

## Recipes

### Filter toolbar

Small selects with icon prefixes next to a [`SearchField`](/docs/components/search-field). Each has an `aria-label` since there's no visible label.

Example `select/recipe-filters`: source in https://desyne.dev/docs/components/select.md

### Settings list

A select aligned to the end of each row, labelled by the row's title via `aria-labelledby`.

Example `select/recipe-settings`: source in https://desyne.dev/docs/components/select.md

### Dependent selects

The second select's `items` depend on the first. Reset the child value when the parent changes.

Example `select/recipe-dependent`: source in https://desyne.dev/docs/components/select.md

## Accessibility

* The trigger is a button with `aria-haspopup="listbox"`; the selected value and label are announced together.
* Always provide a label: `label`, `aria-label`, or `aria-labelledby`.
* When `name` is set, a visually hidden native `<select>` is rendered so browser autofill and form submission work.
* `description` and `errorMessage` are linked to the trigger with `aria-describedby`.
* Typeahead works both on the closed trigger and inside the open list.

### Keyboard

| Key                                                               | Action                                     |
| ----------------------------------------------------------------- | ------------------------------------------ |
| <kbd>Space</kbd> / <kbd>Enter</kbd> / <kbd>↓</kbd> / <kbd>↑</kbd> | Opens the list                             |
| <kbd>↓</kbd> / <kbd>↑</kbd>                                       | Moves focus between options                |
| <kbd>Home</kbd> / <kbd>End</kbd>                                  | Focuses the first / last option            |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                         | Moves focus by a page                      |
| <kbd>Enter</kbd> / <kbd>Space</kbd>                               | Selects the focused option and closes      |
| <kbd>Esc</kbd>                                                    | Closes the list without changing the value |
| Any character                                                     | Typeahead to the first matching option     |

## Styling

### Data attributes

On the `Select` root (use `group-data-*/field:` to style children):

| Attribute                             | Present when                                     |
| ------------------------------------- | ------------------------------------------------ |
| `data-open`                           | The list is open                                 |
| `data-focused` / `data-focus-visible` | The trigger has focus / keyboard focus           |
| `data-disabled`                       | `isDisabled` is true                             |
| `data-invalid`                        | Validation failed                                |
| `data-required`                       | `isRequired` is true (adds the `*` to the label) |

On each `SelectItem`:

| Attribute                       | Present when                         |
| ------------------------------- | ------------------------------------ |
| `data-focused` / `data-hovered` | The option has virtual focus / hover |
| `data-selected`                 | The option is the current value      |
| `data-disabled`                 | The option is in `disabledKeys`      |

### Slots

| `data-slot`                           | Element            |
| ------------------------------------- | ------------------ |
| `select`                              | Root               |
| `label`, `description`, `field-error` | Field text         |
| `popover`, `list-box`                 | Overlay and list   |
| `list-box-item`, `list-box-section`   | Options and groups |

The popover is at least as wide as the trigger (`min-w-(--trigger-width)`). Pass a `className` on `Select` to size the whole field.

## API Reference

### Select

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text shown under the trigger.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message.&#x22; },
  placeholder: { type: &#x22;string&#x22;, default: '&#x22;Select an item&#x22;', description: &#x22;Shown when nothing is selected.&#x22; },
  prefix: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon or element shown before the value in the trigger.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static SelectItems / SelectSections, or a render function.&#x22; },
  selectedKey: { type: &#x22;Key | null&#x22;, description: &#x22;Controlled value.&#x22; },
  defaultSelectedKey: { type: &#x22;Key&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onSelectionChange: { type: &#x22;(key: Key | null) => void&#x22;, description: &#x22;Called when the value changes.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Options that can't be selected.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state of the list.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the list opens or closes.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires a value before the form can submit.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state (e.g. for server errors).&#x22; },
  validate: { type: &#x22;(key: Key | null) => string | string[] | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  autoComplete: { type: &#x22;string&#x22;, description: &#x22;Autofill hint for the hidden native select.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  className: { type: &#x22;string | ((state: SelectRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Select`](https://react-aria.adobe.com/Select#api).

### SelectItem

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Becomes the value of the select.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Plain text for typeahead and the hidden select. Required when children aren't a string.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this option (same as adding it to disabledKeys).&#x22; },
  value: { type: &#x22;T&#x22;, description: &#x22;The item object, when using dynamic collections.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Turns the option into a link.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when the option is selected.&#x22; },
  className: { type: &#x22;string | ((state: ListBoxItemRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: ListBoxItemRenderProps) => ReactNode)&#x22; },
}"
/>

### SelectSection

<TypeTable
  type="{
  title: { type: &#x22;string&#x22;, description: &#x22;Heading shown above the group.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22; },
  id: { type: &#x22;Key&#x22; },
}"
/>

### SelectItemLabel / SelectItemDescription

Accept every prop of React Aria's [`Text`](https://react-aria.adobe.com/ListBox#text-slots). They set `slot="label"` and `slot="description"` so the option's accessible name and description are wired up automatically.

## Related

* [Combo Box](/docs/components/combobox) — searchable select with free-form input.
* [List Box](/docs/components/list-box) — the same list, always visible, with multiple selection.
* [Radio Group](/docs/components/radio-group) — for a handful of visible options.
* [Text Field](/docs/components/text-field) — shares the same field variants and sizes.

---

# Combo Box

Source: https://desyne.dev/docs/components/combobox

> A text input with a filterable list of options. Filters as you type, supports rich items, sections, custom values, async loading, custom filters, controlled input and selection, validation and form submission.

```tsx title="combobox/demo.tsx"
"use client";

import { ComboBox, ComboBoxItem } from "@/components/ui/combobox";

const countries = [
  "Australia",
  "Canada",
  "France",
  "Germany",
  "India",
  "Japan",
  "Nepal",
  "Norway",
  "United Kingdom",
  "United States",
].map((name) => ({ id: name, name }));

export default function ComboBoxDemo() {
  return (
    <ComboBox
      className="w-full max-w-64"
      label="Country"
      placeholder="Search countries…"
      defaultItems={countries}
    >
      {(item) => <ComboBoxItem>{item.name}</ComboBoxItem>}
    </ComboBox>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/combobox
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  ComboBox,
  ComboBoxItem,
  ComboBoxItemDescription,
  ComboBoxItemLabel,
  ComboBoxSection,
} from "@/components/ui/combobox";
```

```tsx
<ComboBox label="Country" placeholder="Search countries…" defaultItems={countries}>
  {(country) => <ComboBoxItem>{country.name}</ComboBoxItem>}
</ComboBox>
```

A combo box has two values: the selected option (`value`, a `Key` or `null`) and the text in the input (`inputValue`). Choosing an option sets both; typing only changes the text until an option is committed.

<Callout title="defaultItems filters for you, items doesn't">
  Pass `defaultItems` (or static children) and the list filters as the user
  types, using a case- and accent-insensitive "contains" match. Pass `items`
  when you filter yourself, for example against a server, and update them from
  `onInputChange`.
</Callout>

### When to use

* Combo Box — long lists (roughly 15+) users will search, or when free-form input is allowed.
* [Select](/docs/components/select) — a short list where browsing is faster than typing, and only listed values are valid.
* [Search Field](/docs/components/search-field) — a query that filters content elsewhere, not a value to pick.
* [Command Palette](/docs/components/command-palette) — a global launcher for actions and navigation.
* [Tag Group](/docs/components/tag-group) with a combo box — picking several values; see the [tag picker recipe](#tag-picker).

## Anatomy

```tsx
<ComboBox>                         {/* root: label, input, description, error */}
  <ComboBoxSection title="…">      {/* optional group with a heading */}
    <ComboBoxItem id="…">          {/* option */}
      <Icon />
      <ComboBoxItemLabel />        {/* primary text */}
      <ComboBoxItemDescription />  {/* secondary text */}
    </ComboBoxItem>
  </ComboBoxSection>
</ComboBox>
```

| Part                      | Renders                     | Notes                                                                                                                                                 |
| ------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ComboBox`                | `<div>` + popover           | Root. Carries `data-slot="combobox"` and the `group/field` class. Wraps the label, the input group, description, error message and the list popover.  |
| Input group               | `FieldGroup`                | The visible box: `prefix`, the `<input role="combobox">`, and a chevron button that toggles the list.                                                 |
| Chevron button            | `<button>`                  | Opens the full list. Skipped in the tab order. It's the combo box's React Aria button, so don't put other React Aria buttons in `prefix`.             |
| Popover                   | `Popover` + `ListBox`       | At least as wide as the input group. Shows `emptyMessage` when nothing matches (unless `allowsEmptyCollection={false}`).                              |
| `ComboBoxItem`            | `role="option"`             | An option. Needs a unique `id` (or an `id` on the item object), and `textValue` when its children aren't a plain string. Shows a check when selected. |
| `ComboBoxItemLabel`       | `<span slot="label">`       | Primary text of a rich item.                                                                                                                          |
| `ComboBoxItemDescription` | `<span slot="description">` | Secondary text of a rich item.                                                                                                                        |
| `ComboBoxSection`         | `role="group"`              | Groups options under an optional `title`.                                                                                                             |
| Hidden `<input>`          | `<input type="hidden">`     | Rendered when `name` is set. Submits the selected key (or the text, see [form submission](#form-submission)).                                         |

The input shows the selected option's `textValue`, so rich items still display as plain text once chosen.

## Examples

### Variants

`outline` (default), `filled` for dense or tinted surfaces, and `underlined` for minimal forms. The same variants apply to every field component.

Example `combobox/variants`: source in https://desyne.dev/docs/components/combobox.md

### Sizes

`sm` (28px), `md` (32px, default) and `lg` (40px), matching the buttons and other fields.

Example `combobox/sizes`: source in https://desyne.dev/docs/components/combobox.md

### Rich items and prefix

Compose icons or avatars with `ComboBoxItemLabel` and `ComboBoxItemDescription`, and set `textValue` so filtering and the input text use the name. `prefix` adds an icon to the input.

Example `combobox/rich-items`: source in https://desyne.dev/docs/components/combobox.md

### Sections

Pass sections as `defaultItems` and render each with `ComboBoxSection`, giving it `items` and a render function. Filtering applies to the options inside every section.

Example `combobox/sections`: source in https://desyne.dev/docs/components/combobox.md

### Empty state

When nothing matches, the list stays open and shows `emptyMessage` (default "No results"), so users know the search worked. Type something that isn't in the list below to see it. Pass `allowsEmptyCollection={false}` to close the list instead.

Example `combobox/empty-state`: source in https://desyne.dev/docs/components/combobox.md

### Menu trigger

`menuTrigger` controls when the list opens: `input` (default) when the user types, `focus` as soon as the input is focused, which suits short lists of suggestions, and `manual` only from the chevron button or the arrow keys.

Example `combobox/menu-trigger`: source in https://desyne.dev/docs/components/combobox.md

### Custom values

`allowsCustomValue` accepts text that isn't in the list. The value stays `null` for custom text, so read `inputValue` (or the submitted form value) instead.

Example `combobox/custom-value`: source in https://desyne.dev/docs/components/combobox.md

### Controlled

Control the selection with `value` / `onChange` and the text with `inputValue` / `onInputChange`. When you control both, update the input text yourself when the selection changes, and reset both to clear the field.

Example `combobox/controlled`: source in https://desyne.dev/docs/components/combobox.md

### Async loading

React Aria's `useAsyncList` loads items as the user types and aborts stale requests. Wire its `filterText` to `inputValue` and pass the results as `items`. Swapping the `prefix` for a [`Spinner`](/docs/components/spinner) shows progress in place.

Example `combobox/async`: source in https://desyne.dev/docs/components/combobox.md

### Custom filter

`defaultFilter` replaces the built-in "contains" match. React Aria's `useFilter` gives you locale-aware `startsWith`, `contains` and `endsWith`.

Example `combobox/custom-filter`: source in https://desyne.dev/docs/components/combobox.md

### Disabled

`isDisabled` disables the input and the button; `disabledKeys` keeps specific options visible but unselectable. Use `description` to explain why.

Example `combobox/disabled`: source in https://desyne.dev/docs/components/combobox.md

### Required and validation

`isRequired` blocks form submission until an option is selected and shows the browser's message. Unless `allowsCustomValue` is set, the input reverts to the selected option's text on blur, so the value is always a listed option.

Example `combobox/validation`: source in https://desyne.dev/docs/components/combobox.md

### Custom validation

`validate` receives `{ value, inputValue }` and returns an error string or `null`. With `validationBehavior="aria"` on the `Form`, errors show live as the selection changes.

Example `combobox/custom-validation`: source in https://desyne.dev/docs/components/combobox.md

### Form submission

With a `name`, the selected key is submitted through a hidden input. Set `formValue="text"` to submit the input text instead; with `allowsCustomValue`, the text is always submitted.

Example `combobox/form`: source in https://desyne.dev/docs/components/combobox.md

## Recipes

### Tag picker

Multiple selection built from a combo box and a [`TagGroup`](/docs/components/tag-group). The combo box stays empty (`value={null}`), each choice is added as a removable tag, and chosen options drop out of the list.

Example `combobox/recipe-tag-picker`: source in https://desyne.dev/docs/components/combobox.md

### Dependent address fields

A country combo box drives the options, label and reset of the region combo box, alongside [text fields](/docs/components/text-field) with `autoComplete` hints.

Example `combobox/recipe-shipping`: source in https://desyne.dev/docs/components/combobox.md

## Accessibility

* The input has `role="combobox"` with `aria-expanded`, `aria-controls` and `aria-activedescendant`, so focus stays in the input while options are highlighted.
* Always provide a label: `label`, `aria-label`, or `aria-labelledby`.
* Screen readers announce the number of available options as the list changes, and the selected option when it's committed.
* `description` and `errorMessage` are linked to the input with `aria-describedby`.
* The chevron button is skipped in the tab order because the arrow keys open the list from the input.
* Items that aren't plain strings need `textValue` so they can be filtered, announced and shown in the input.

### Keyboard

| Key                         | Action                                                                       |
| --------------------------- | ---------------------------------------------------------------------------- |
| Typing                      | Filters the list and opens it (with `menuTrigger="input"`)                   |
| <kbd>↓</kbd> / <kbd>↑</kbd> | Opens the list, focusing the first / last option; then moves between options |
| <kbd>Enter</kbd>            | Selects the focused option and closes the list                               |
| <kbd>Tab</kbd>              | Selects the focused option (if the list is open) and moves focus on          |
| <kbd>Esc</kbd>              | Closes the list and reverts the input to the selected option's text          |
| <kbd>←</kbd> / <kbd>→</kbd> | Moves the text cursor, leaving the list                                      |

## Styling

### Data attributes

On the `ComboBox` root (use `group-data-*/field:` to style children):

| Attribute       | Present when         |
| --------------- | -------------------- |
| `data-open`     | The list is open     |
| `data-focused`  | The input has focus  |
| `data-disabled` | `isDisabled` is true |
| `data-readonly` | `isReadOnly` is true |
| `data-invalid`  | Validation failed    |
| `data-required` | `isRequired` is true |

On each `ComboBoxItem`:

| Attribute                       | Present when                        |
| ------------------------------- | ----------------------------------- |
| `data-focused` / `data-hovered` | The option is highlighted / hovered |
| `data-selected`                 | The option is the current value     |
| `data-disabled`                 | The option is in `disabledKeys`     |

### Slots

| `data-slot`                           | Element                 |
| ------------------------------------- | ----------------------- |
| `combobox`                            | Root                    |
| `label`, `description`, `field-error` | Field text              |
| `field-group`, `field-input`          | Input box and `<input>` |
| `popover`, `list-box`                 | Overlay and list        |
| `list-box-item`, `list-box-section`   | Options and groups      |

The popover is at least as wide as the input group (`min-w-(--trigger-width)`). Pass a `className` on `ComboBox` to size the whole field; it also accepts a function of the render state (`isOpen`, `isDisabled`, `isInvalid`, `isReadOnly`, `isRequired`). Option styles come from `listBoxItemStyles` in `list-box.tsx`.

## API Reference

### ComboBox

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text shown under the input.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message while invalid.&#x22; },
  placeholder: { type: &#x22;string&#x22;, description: &#x22;Shown while the input is empty.&#x22; },
  prefix: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon or element shown before the input.&#x22; },
  emptyMessage: { type: &#x22;ReactNode&#x22;, default: '&#x22;No results&#x22;', description: &#x22;Shown in the list when nothing matches.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static ComboBoxItems / ComboBoxSections, or a render function for items.&#x22; },
  defaultItems: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items filtered automatically as the user types.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items you filter yourself (e.g. async results).&#x22; },
  value: { type: &#x22;Key | null&#x22;, description: &#x22;Controlled selected key.&#x22; },
  defaultValue: { type: &#x22;Key | null&#x22;, description: &#x22;Uncontrolled initial selected key.&#x22; },
  onChange: { type: &#x22;(value: Key | null) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  inputValue: { type: &#x22;string&#x22;, description: &#x22;Controlled input text.&#x22; },
  defaultInputValue: { type: &#x22;string&#x22;, description: &#x22;Uncontrolled initial input text.&#x22; },
  onInputChange: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called when the input text changes.&#x22; },
  allowsCustomValue: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Accepts text that doesn't match an option.&#x22; },
  allowsEmptyCollection: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Keeps the list open (showing emptyMessage) when nothing matches. Set false to close the list instead.&#x22; },
  defaultFilter: { type: &#x22;(textValue: string, inputValue: string) => boolean&#x22;, description: 'Replaces the default locale-aware &#x22;contains&#x22; filter.' },
  menuTrigger: { type: '&#x22;input&#x22; | &#x22;focus&#x22; | &#x22;manual&#x22;', default: '&#x22;input&#x22;', description: &#x22;What opens the list.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Options that can't be selected.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean, menuTrigger?: MenuTriggerAction) => void&#x22;, description: &#x22;Called when the list opens or closes.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires a selection before the form can submit.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state, e.g. for server errors.&#x22; },
  validate: { type: &#x22;(v: { value: Key | null, inputValue: string }) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live. Inherits from a parent Form.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  formValue: { type: '&#x22;key&#x22; | &#x22;text&#x22;', default: '&#x22;key&#x22;', description: &#x22;Whether the key or the input text is submitted. Always text with allowsCustomValue.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  selectedKey: { type: &#x22;Key | null&#x22;, description: &#x22;Deprecated alias of value.&#x22; },
  defaultSelectedKey: { type: &#x22;Key | null&#x22;, description: &#x22;Deprecated alias of defaultValue.&#x22; },
  onSelectionChange: { type: &#x22;(key: Key | null) => void&#x22;, description: &#x22;Deprecated alias of onChange.&#x22; },
  className: { type: &#x22;string | ((state: ComboBoxRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ComboBox`](https://react-aria.adobe.com/ComboBox#api). This wrapper is single-selection only.

### ComboBoxItem

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Becomes the value of the combo box.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Plain text for filtering, announcements and the input. Required when children aren't a string.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this option (same as adding it to disabledKeys).&#x22; },
  value: { type: &#x22;T&#x22;, description: &#x22;The item object, when using dynamic collections.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Turns the option into a link; Enter opens it instead of selecting.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when the option is activated. Action options aren't selected.&#x22; },
  className: { type: &#x22;string | ((state: ListBoxItemRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: ListBoxItemRenderProps) => ReactNode)&#x22; },
}"
/>

### ComboBoxSection

<TypeTable
  type="{
  title: { type: &#x22;string&#x22;, description: &#x22;Heading shown above the group.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22; },
  id: { type: &#x22;Key&#x22;, description: &#x22;Required for dynamic sections.&#x22; },
}"
/>

### ComboBoxItemLabel / ComboBoxItemDescription

Accept every prop of React Aria's [`Text`](https://react-aria.adobe.com/ListBox#text-slots). They set `slot="label"` and `slot="description"` so each option's accessible name and description are wired up automatically.

## Related

* [Select](/docs/components/select) — the same list without typing.
* [List Box](/docs/components/list-box) — the list on its own, always visible, with multiple selection.
* [Tag Group](/docs/components/tag-group) — for showing several chosen values.
* [Search Field](/docs/components/search-field) — for queries rather than values.

---

# Checkbox

Source: https://desyne.dev/docs/components/checkbox

> Lets users turn a single option on or off, or pick any number of options from a group. Supports descriptions, an indeterminate state, card layouts, validation and native form submission.

```tsx title="checkbox/demo.tsx"
"use client";

import { Checkbox } from "@/components/ui/checkbox";

export default function CheckboxDemo() {
  return <Checkbox defaultSelected>Email me about product updates</Checkbox>;
}
```

## Installation

```bash
npx shadcn@latest add @desyne/checkbox
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

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

```tsx
<Checkbox>Remember me</Checkbox>

<CheckboxGroup label="Notify me about" defaultValue={["mentions"]}>
  <Checkbox value="mentions">Mentions</Checkbox>
  <Checkbox value="comments">Comments</Checkbox>
</CheckboxGroup>
```

A standalone `Checkbox` owns a boolean (`isSelected`). Inside a `CheckboxGroup`, each checkbox needs a `value` and the group owns a `string[]` of the selected values.

### When to use

* Checkbox — independent options, any number of which can be on, usually confirmed with a submit button.
* [Switch](/docs/components/switch) — a single setting that takes effect immediately, like turning on dark mode.
* [Radio Group](/docs/components/radio-group) — exactly one choice from a small, visible set.
* [Toggle Button Group](/docs/components/toggle-button-group) — compact multi-select inside toolbars.
* [List Box](/docs/components/list-box) or [Tag Group](/docs/components/tag-group) — multi-select from a long or dynamic list.

## Anatomy

`Checkbox` is built on React Aria's `CheckboxField` and `CheckboxButton`. You only render `Checkbox`; it composes the parts for you:

```tsx
<CheckboxGroup>                  {/* label, description, error message */}
  <Checkbox value="…">           {/* CheckboxField: <div>, owns state and validation */}
    {/* CheckboxButton: <label> wrapping a hidden <input type="checkbox"> */}
    {/*   box + children + description (Text slot="description") */}
    {/* FieldError: standalone checkboxes only */}
  </Checkbox>
</CheckboxGroup>
```

| Part                              | Renders                                                           | Notes                                                                                                                                                                                                                                 |
| --------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Checkbox` root (`CheckboxField`) | `<div data-slot="checkbox-field">`                                | Holds the checked state, `name` / `value`, validation and the ARIA wiring between the input, description and error. Carries `data-selected`, `data-indeterminate`, `data-disabled`, `data-readonly`, `data-invalid`, `data-required`. |
| `CheckboxButton`                  | `<label data-slot="checkbox">` + hidden `<input type="checkbox">` | The clickable area: box, label and description. Receives `className`, `style`, `render`, `children` and hover handlers, and carries every interaction attribute.                                                                      |
| Box                               | `<span data-slot="checkbox-indicator">`                           | Shows a check icon, or a minus icon when `isIndeterminate`. Sized by `size`.                                                                                                                                                          |
| Description                       | `<span slot="description">`                                       | From the `description` prop. Rendered inside the label so the whole area stays clickable, and linked to the input with `aria-describedby`.                                                                                            |
| `FieldError`                      | `<div data-slot="field-error">`                                   | Standalone checkboxes only: shows `errorMessage` or the browser message when validation fails. Inside a group, the group shows one error instead.                                                                                     |
| `CheckboxGroup`                   | `<div role="group">`                                              | Wraps the label, description, the checkboxes and the error message.                                                                                                                                                                   |
| Group label / description         | `<span>`                                                          | Rendered from the group's `label` and `description` props.                                                                                                                                                                            |

## Examples

### States

Checked, unchecked and indeterminate are the three visual values. `isInvalid` turns the box red, `isDisabled` dims it and removes it from the tab order, and `isReadOnly` keeps it focusable but ignores changes.

Example `checkbox/states`: source in https://desyne.dev/docs/components/checkbox.md

### Sizes

`md` (16px) is the default. `sm` fits dense tables and filters; `lg` also bumps the label to `text-base` for touch-first layouts.

Example `checkbox/sizes`: source in https://desyne.dev/docs/components/checkbox.md

### With description

`description` adds secondary text under the label and aligns the box to the first line. Use it to explain the consequence of an option instead of a long label.

Example `checkbox/description`: source in https://desyne.dev/docs/components/checkbox.md

### Controlled

Use `isSelected` and `onChange` to own the value, for example to show or persist it elsewhere. Use `defaultSelected` when you only need the initial value.

Example `checkbox/controlled`: source in https://desyne.dev/docs/components/checkbox.md

### Group

`CheckboxGroup` renders a shared label and description, gives the checkboxes `role="group"`, and collects the selected `value`s into an array.

Example `checkbox/group`: source in https://desyne.dev/docs/components/checkbox.md

### Horizontal

`orientation="horizontal"` lays the checkboxes out in a wrapping row. Keep labels short; switch back to vertical as soon as options wrap to a second line.

Example `checkbox/horizontal`: source in https://desyne.dev/docs/components/checkbox.md

### Disabled and read-only in a group

`isDisabled` on a single checkbox locks just that option; use the description to say why. `isReadOnly` on the group shows the current value without letting users change it, and keeps every option focusable.

Example `checkbox/group-disabled`: source in https://desyne.dev/docs/components/checkbox.md

### Controlled group

Pass `value` and `onChange` to the group to own the array of selected values.

Example `checkbox/group-controlled`: source in https://desyne.dev/docs/components/checkbox.md

### Indeterminate

A parent checkbox for a set of children. Set `isIndeterminate` when only some children are selected. It's purely visual (announced as "mixed"), so you must control it; pressing the checkbox calls `onChange` with the next value.

Example `checkbox/indeterminate`: source in https://desyne.dev/docs/components/checkbox.md

### Cards

`className` is merged with the base styles, so a border, padding and `data-selected:` styles turn a checkbox with a `description` into a selectable card. The whole card is the label, so it's all clickable.

Example `checkbox/cards`: source in https://desyne.dev/docs/components/checkbox.md

### Required and validation

`isRequired` on a group requires at least one selection; on a standalone checkbox it requires it to be checked. With the default native validation, submitting the form shows the `errorMessage` (or the browser message) under the group or the standalone checkbox and focuses the first invalid field. A required group also adds a `*` to its label.

Example `checkbox/validation`: source in https://desyne.dev/docs/components/checkbox.md

### Custom validation

`validate` receives the selected values and returns an error string, or `null` when valid. With `validationBehavior="aria"` the error shows as soon as the value changes instead of on submit.

Example `checkbox/custom-validation`: source in https://desyne.dev/docs/components/checkbox.md

### Form submission

Give the group a `name` and every checked `value` is submitted under it; read them with `FormData.getAll()`. A standalone checkbox submits its `value` (`"on"` by default) only when checked.

Example `checkbox/form`: source in https://desyne.dev/docs/components/checkbox.md

## Recipes

### Bulk selection

A select-all checkbox in a list header, indeterminate while only some rows are selected, with bulk actions that appear once anything is selected. Row checkboxes have no visible label, so each gets an `aria-label`.

Example `checkbox/recipe-bulk-select`: source in https://desyne.dev/docs/components/checkbox.md

### Notification matrix

A table of events × channels. Each checkbox gets an `aria-label` combining its row and column, since the visual headers aren't associated with it.

Example `checkbox/recipe-notification-matrix`: source in https://desyne.dev/docs/components/checkbox.md

### Onboarding checklist

A controlled group drives a [`ProgressBar`](/docs/components/progress-bar). `children` is a render function, so completed steps are struck through.

Example `checkbox/recipe-checklist`: source in https://desyne.dev/docs/components/checkbox.md

## Accessibility

* Each checkbox is a native `<input type="checkbox">`, visually hidden inside a `<label>`, so clicking anywhere on the label toggles it and it works with every assistive technology and with native forms.
* `isIndeterminate` sets the input's `indeterminate` property, which screen readers announce as "mixed".
* Checkboxes without visible text (table rows, matrices) need an `aria-label` or `aria-labelledby`.
* `CheckboxGroup` renders `role="group"` labelled by its `label`; its description and error message are linked with `aria-describedby`.
* `description` on a `Checkbox` is linked to the input with `aria-describedby`, so it's announced as the description rather than as part of the name. It sits inside the `<label>` (so it's clickable) but is hidden from the name computation.
* A standalone checkbox's error message is linked to the input with `aria-describedby` as well.
* The focus ring only appears for keyboard focus (`data-focus-visible`).

### Keyboard

| Key              | Action                                                                           |
| ---------------- | -------------------------------------------------------------------------------- |
| <kbd>Tab</kbd>   | Moves focus to the next checkbox. Every checkbox in a group is its own tab stop. |
| <kbd>Space</kbd> | Toggles the focused checkbox                                                     |

## Styling

### Data attributes

The attributes you'll style against are on the `<label>` (`CheckboxButton`), which is also where `className` goes. Target the box or label text from it with `group-data-*/checkbox:`. The outer `CheckboxField` `<div>` repeats the state attributes (not the interaction ones) and is a `group/checkbox-field`, for styling siblings such as the error message.

| Attribute                             | `<label>` (`CheckboxButton`) | `<div>` (`CheckboxField`) | Present when                             |
| ------------------------------------- | ---------------------------- | ------------------------- | ---------------------------------------- |
| `data-selected`                       | Yes                          | Yes                       | Checked                                  |
| `data-indeterminate`                  | Yes                          | Yes                       | `isIndeterminate` is true                |
| `data-hovered`                        | Yes                          | No                        | Hovered with a mouse or pen              |
| `data-pressed`                        | Yes                          | No                        | Being pressed                            |
| `data-focused` / `data-focus-visible` | Yes                          | No                        | Focused / focused with the keyboard      |
| `data-disabled`                       | Yes                          | Yes                       | Disabled, directly or through the group  |
| `data-readonly`                       | Yes                          | Yes                       | Read-only, directly or through the group |
| `data-invalid`                        | Yes                          | Yes                       | Invalid, directly or through the group   |
| `data-required`                       | Yes                          | Yes                       | Required                                 |

On `CheckboxGroup` (children can use `group-data-*/field:`): `data-disabled`, `data-readonly`, `data-required`, `data-invalid`.

### Slots

| `data-slot`                           | Element                                                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `checkbox-field`                      | Each checkbox's outer `<div>` (`CheckboxField`)                                                                    |
| `checkbox`                            | Each checkbox's `<label>` (`CheckboxButton`), where `className` goes                                               |
| `checkbox-indicator`                  | The box                                                                                                            |
| `checkbox-group`                      | Group root                                                                                                         |
| `label`, `description`, `field-error` | Group label, description and error message; `description` and `field-error` are also used on a standalone checkbox |

### Color

The box uses the `--brand` and `--brand-foreground` theme variables (red `--destructive` when invalid). Override them on a single checkbox or a whole group for a one-off color:

```tsx
<Checkbox className="[--brand:var(--color-emerald-600)] [--brand-foreground:white]">
  Mark as paid
</Checkbox>
```

### Render props

`className` and `children` accept a function of the `CheckboxButton` state (`isSelected`, `isIndeterminate`, `isHovered`, `isPressed`, `isFocusVisible`, `isDisabled`, `isReadOnly`, `isInvalid`, `isRequired`):

```tsx
<Checkbox className={({ isSelected }) => (isSelected ? "font-medium" : "")}>
  {({ isIndeterminate }) => (isIndeterminate ? "Some selected" : "Select all")}
</Checkbox>
```

## API Reference

### Checkbox

<TypeTable
  type="{
  children: { type: &#x22;ReactNode | ((state: CheckboxButtonRenderProps) => ReactNode)&#x22;, description: &#x22;The label. With a function, it receives the render state.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Secondary text under the label, linked with aria-describedby. Makes the label bold and aligns the box to the first line.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message of a standalone checkbox. Ignored inside a CheckboxGroup, which shows its own.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Box size. lg also uses text-base for the label.&#x22; },
  isSelected: { type: &#x22;boolean&#x22;, description: &#x22;Controlled checked state.&#x22; },
  defaultSelected: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial checked state.&#x22; },
  onChange: { type: &#x22;(isSelected: boolean) => void&#x22;, description: &#x22;Called when the checked state changes.&#x22; },
  isIndeterminate: { type: &#x22;boolean&#x22;, description: &#x22;Shows a minus icon and announces the state as mixed. Must be controlled.&#x22; },
  value: { type: &#x22;string&#x22;, description: &#x22;Value submitted with the form, and the item's value inside a CheckboxGroup. Defaults to \&#x22;on\&#x22; natively.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form (standalone checkboxes).&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the input belongs to.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Focusable but can't be changed.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Must be checked before the form can submit.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state.&#x22; },
  validate: { type: &#x22;(isSelected: boolean) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation for a standalone checkbox.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;' },
  autoFocus: { type: &#x22;boolean&#x22; },
  inputRef: { type: &#x22;Ref<HTMLInputElement>&#x22;, description: &#x22;Ref to the hidden input.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Press events are also supported: onPressStart, onPressEnd, onPressChange, onPressUp.&#x22; },
  onHoverChange: { type: &#x22;(isHovered: boolean) => void&#x22;, description: &#x22;onHoverStart and onHoverEnd are also supported. Applied to the label.&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22;, description: &#x22;onBlur and onFocusChange are also supported.&#x22; },
  className: { type: &#x22;string | ((state: CheckboxButtonRenderProps) => string)&#x22;, description: &#x22;Classes for the <label> (CheckboxButton).&#x22; },
  style: { type: &#x22;CSSProperties | ((state: CheckboxButtonRenderProps) => CSSProperties)&#x22;, description: &#x22;Inline styles for the <label>.&#x22; },
  slot: { type: &#x22;string | null&#x22;, description: &#x22;Slot name, e.g. \&#x22;selection\&#x22; inside a Table or GridList row. Applied to the CheckboxField.&#x22; },
  ref: { type: &#x22;Ref<HTMLLabelElement>&#x22;, description: &#x22;Ref to the <label>.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there are no children.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`CheckboxField`](https://react-aria.adobe.com/Checkbox#checkboxfield). `className`, `style`, `render`, `children` and the hover handlers go to the [`CheckboxButton`](https://react-aria.adobe.com/Checkbox#checkboxbutton) instead; everything else (state, `name`, `value`, validation, focus and press handlers, ARIA and DOM attributes) goes to the `CheckboxField`.

### CheckboxGroup

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible group label. Use aria-label or aria-labelledby if there's none.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text under the label.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message.&#x22; },
  orientation: { type: '&#x22;vertical&#x22; | &#x22;horizontal&#x22;', default: '&#x22;vertical&#x22;', description: &#x22;Layout of the checkboxes. Visual only.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Checkbox elements, each with a value.&#x22; },
  value: { type: &#x22;string[]&#x22;, description: &#x22;Controlled selected values.&#x22; },
  defaultValue: { type: &#x22;string[]&#x22;, description: &#x22;Uncontrolled initial selected values.&#x22; },
  onChange: { type: &#x22;(value: string[]) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name applied to every checkbox for form submission.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the inputs belong to.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables every checkbox.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Makes every checkbox read-only.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires at least one checkbox to be selected.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state on the group and its checkboxes.&#x22; },
  validate: { type: &#x22;(value: string[]) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the group invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live.&#x22; },
  className: { type: &#x22;string | ((state: CheckboxGroupRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`CheckboxGroup`](https://react-aria.adobe.com/CheckboxGroup).

## Related

* [Switch](/docs/components/switch) — for settings that apply immediately.
* [Radio Group](/docs/components/radio-group) — for a single choice.
* [Toggle Button Group](/docs/components/toggle-button-group) — multi-select as buttons.
* [Table](/docs/components/table) — has built-in row selection with checkboxes.

---

# Radio Group

Source: https://desyne.dev/docs/components/radio-group

> Lets users pick exactly one option from a small set that stays visible. Renders as a simple list or as selectable cards with icons, and supports descriptions, horizontal layout, validation and native form submission.

```tsx title="radio-group/demo.tsx"
"use client";

import { Radio, RadioGroup } from "@/components/ui/radio-group";

export default function RadioGroupDemo() {
  return (
    <RadioGroup label="Notifications" defaultValue="mentions">
      <Radio value="all">All new messages</Radio>
      <Radio value="mentions">Direct messages and mentions</Radio>
      <Radio value="none">Nothing</Radio>
    </RadioGroup>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/radio-group
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { Radio, RadioCard, RadioGroup } from "@/components/ui/radio-group";
```

```tsx
<RadioGroup label="Size" defaultValue="m">
  <Radio value="s">Small</Radio>
  <Radio value="m">Medium</Radio>
  <Radio value="l">Large</Radio>
</RadioGroup>
```

The group owns the value: a single `string` matching one radio's `value`. `Radio` and `RadioCard` can be mixed freely inside the same group.

### When to use

* Radio Group — one choice from about 2–6 options that users should compare side by side.
* [Select](/docs/components/select) — one choice from a longer list, or when space is tight.
* [Checkbox](/docs/components/checkbox) — any number of choices, or a single yes/no that's submitted with a form.
* [Switch](/docs/components/switch) — a single on/off setting that applies immediately.
* [Toggle Button Group](/docs/components/toggle-button-group) — a compact, button-styled choice such as alignment or view mode.

## Anatomy

```tsx
<RadioGroup>                {/* label, description, error message */}
  <Radio value="…">Label</Radio>
  <RadioCard value="…" icon={…} title="…" description="…" />
</RadioGroup>
```

| Part                | Renders                                   | Notes                                                                                               |
| ------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `RadioGroup`        | `<div role="radiogroup">`                 | Wraps the label, description, radios and error message. `orientation` controls the layout.          |
| `Radio`             | `<label>` + hidden `<input type="radio">` | A dot and a label. With `description`, the label becomes a bold title with secondary text under it. |
| `RadioCard`         | `<label>` + hidden `<input type="radio">` | A bordered card with an optional `icon`, a `title`, a `description` and a trailing dot.             |
| Label / Description | `<span>`                                  | Rendered from the group's `label` and `description` props.                                          |
| `FieldError`        | `<div>`                                   | Rendered by the group when validation fails; shows `errorMessage` or the browser message.           |

## Examples

### Horizontal

`orientation="horizontal"` lays radios out in a wrapping row and sets `aria-orientation`. Use it for 2–4 short labels.

Example `radio-group/horizontal`: source in https://desyne.dev/docs/components/radio-group.md

### With descriptions

`description` on a `Radio` adds secondary text under the label. Use it when the labels alone don't explain the difference between options.

Example `radio-group/description`: source in https://desyne.dev/docs/components/radio-group.md

### Disabled and read-only

`isDisabled` on a `Radio` makes just that option unavailable while keeping it visible; explain why in the group's `description`. `isDisabled` on the group disables every option. `isReadOnly` shows the value but ignores changes, and keeps the group focusable.

Example `radio-group/disabled`: source in https://desyne.dev/docs/components/radio-group.md

### Controlled

Use `value` and `onChange` to own the selection. `onChange` receives the selected radio's `value`.

Example `radio-group/controlled`: source in https://desyne.dev/docs/components/radio-group.md

### Cards

`RadioCard` is a larger target with a leading `icon`, a `title` and a `description`. The whole card is the label, and the selected card gets a brand-colored border.

Example `radio-group/cards`: source in https://desyne.dev/docs/components/radio-group.md

### Card grid

In a horizontal group, give each card `flex-1` and a `min-w-*` so they share the row evenly and wrap on narrow screens.

Example `radio-group/card-grid`: source in https://desyne.dev/docs/components/radio-group.md

### With a follow-up input

Control the group to reveal a related field when a specific option is picked, like "Something else". Place the input after the group, not inside a radio's label.

Example `radio-group/with-input`: source in https://desyne.dev/docs/components/radio-group.md

### Required and validation

`isRequired` blocks form submission until an option is selected and adds a `*` to the label. With native validation, the `errorMessage` appears after the first submit attempt.

Example `radio-group/validation`: source in https://desyne.dev/docs/components/radio-group.md

### Custom validation

`validate` receives the selected value and returns an error string, or `null` when valid. With `validationBehavior="aria"` the message updates live as the selection changes.

Example `radio-group/custom-validation`: source in https://desyne.dev/docs/components/radio-group.md

### Form submission

Give the group a `name` and the selected radio's `value` is submitted under it, exactly like native radio buttons.

Example `radio-group/form`: source in https://desyne.dev/docs/components/radio-group.md

## Recipes

### Plan picker

Cards whose `title` is a composed node with a [`Badge`](/docs/components/badge) and a price. A [`Switch`](/docs/components/switch) toggles yearly billing.

Example `radio-group/recipe-plan-picker`: source in https://desyne.dev/docs/components/radio-group.md

### Shipping method

A checkout step where the selected card updates the order total.

Example `radio-group/recipe-shipping`: source in https://desyne.dev/docs/components/radio-group.md

### Privacy settings

Two controlled groups in a settings card, with Save and Discard enabled only when the draft differs from the saved value.

Example `radio-group/recipe-privacy`: source in https://desyne.dev/docs/components/radio-group.md

## Accessibility

* Every radio is a native `<input type="radio">` visually hidden inside a `<label>`, so the whole label (or card) is clickable and native forms work.
* The group has `role="radiogroup"`, is labelled by `label`, and links its description and error message with `aria-describedby`.
* The group is a single tab stop: focus lands on the selected radio (or the first one when nothing is selected), and arrow keys move the selection.
* A group without a visible `label` needs `aria-label` or `aria-labelledby`.
* `description` on a `Radio` and `title` / `description` on a `RadioCard` are inside the `<label>`, so they're read as part of the option's name. Keep them concise.
* The focus ring only appears for keyboard focus (`data-focus-visible`).

### Keyboard

| Key                         | Action                                            |
| --------------------------- | ------------------------------------------------- |
| <kbd>Tab</kbd>              | Moves focus into the group, to the selected radio |
| <kbd>↓</kbd> / <kbd>→</kbd> | Selects the next radio, wrapping to the first     |
| <kbd>↑</kbd> / <kbd>←</kbd> | Selects the previous radio, wrapping to the last  |
| <kbd>Space</kbd>            | Selects the focused radio, if it isn't already    |

## Styling

### Data attributes

On `Radio` and `RadioCard` (target inner parts with `group-data-*/radio:`):

| Attribute                             | Present when                            |
| ------------------------------------- | --------------------------------------- |
| `data-selected`                       | The radio is the group's value          |
| `data-hovered`                        | Hovered with a mouse or pen             |
| `data-pressed`                        | Being pressed                           |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard     |
| `data-disabled`                       | Disabled, directly or through the group |
| `data-readonly`                       | The group is read-only                  |
| `data-invalid`                        | The group is invalid                    |
| `data-required`                       | The group is required                   |

On `RadioGroup` (children can use `group-data-*/field:`):

| Attribute                         | Present when                   |
| --------------------------------- | ------------------------------ |
| `data-orientation`                | `"horizontal"` or `"vertical"` |
| `data-disabled` / `data-readonly` | Disabled / read-only           |
| `data-required` / `data-invalid`  | Required / validation failed   |

### Slots

| `data-slot`                           | Element                                    |
| ------------------------------------- | ------------------------------------------ |
| `radio-group`                         | Group root                                 |
| `radio`                               | Each `Radio`'s `<label>` root              |
| `radio-card`                          | Each `RadioCard`'s `<label>` root          |
| `label`, `description`, `field-error` | Group label, description and error message |

### Color

The dot, hover border and selected card use the `--brand` theme variable. Override it on a group or a single radio:

```tsx
<RadioGroup label="Status" className="[--brand:var(--color-emerald-600)]">
  …
</RadioGroup>
```

### Render props

`Radio`'s `className` and `children` accept a function of its state; `RadioCard`'s `className` does too:

```tsx
<Radio value="pro" className={({ isSelected }) => (isSelected ? "font-medium" : "")}>
  Pro
</Radio>
```

## API Reference

### RadioGroup

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible group label. Use aria-label or aria-labelledby if there's none.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text under the label.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message.&#x22; },
  orientation: { type: '&#x22;vertical&#x22; | &#x22;horizontal&#x22;', default: '&#x22;vertical&#x22;', description: &#x22;Layout and aria-orientation.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Radio and RadioCard elements.&#x22; },
  value: { type: &#x22;string | null&#x22;, description: &#x22;Controlled selected value.&#x22; },
  defaultValue: { type: &#x22;string | null&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the inputs belong to.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables every radio.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shows the value but ignores changes.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires a selection before the form can submit.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state (e.g. for server errors).&#x22; },
  validate: { type: &#x22;(value: string | null) => ValidationError | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the group invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live.&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22;, description: &#x22;onBlur and onFocusChange are also supported.&#x22; },
  className: { type: &#x22;string | ((state: RadioGroupRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`RadioGroup`](https://react-aria.adobe.com/RadioGroup#api).

### Radio

<TypeTable
  type="{
  value: { type: &#x22;string&#x22;, description: &#x22;Required. The value this radio represents.&#x22; },
  children: { type: &#x22;ReactNode | ((state: RadioRenderProps) => ReactNode)&#x22;, description: &#x22;The label.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Secondary text under the label.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables this radio only.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  inputRef: { type: &#x22;Ref<HTMLInputElement>&#x22;, description: &#x22;Ref to the hidden input.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;onPressStart, onPressEnd, onPressChange and onPressUp are also supported.&#x22; },
  onHoverChange: { type: &#x22;(isHovered: boolean) => void&#x22; },
  className: { type: &#x22;string | ((state: RadioRenderProps) => string)&#x22;, description: &#x22;Classes for the <label> root.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there are no children.&#x22; },
}"
/>

### RadioCard

<TypeTable
  type="{
  value: { type: &#x22;string&#x22;, description: &#x22;Required. The value this card represents.&#x22; },
  title: { type: &#x22;ReactNode&#x22;, description: &#x22;Primary text. Can be a composed node (badge, price…).&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Secondary text under the title.&#x22; },
  icon: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon shown in a tinted square on the leading side.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  inputRef: { type: &#x22;Ref<HTMLInputElement>&#x22; },
  className: { type: &#x22;string | ((state: RadioRenderProps) => string)&#x22;, description: &#x22;Classes for the card.&#x22; },
}"
/>

`RadioCard` accepts the same React Aria props as `Radio`, except `children`: its content comes from `title`, `description` and `icon`. See React Aria's [`Radio`](https://react-aria.adobe.com/RadioGroup#radio) props.

## Related

* [Checkbox](/docs/components/checkbox) — for multiple choices.
* [Select](/docs/components/select) — for a single choice from a longer list.
* [Toggle Button Group](/docs/components/toggle-button-group) — single selection as buttons.
* [Switch](/docs/components/switch) — for an on/off setting.

---

# Switch

Source: https://desyne.dev/docs/components/switch

> Turns a single setting on or off, taking effect immediately. Three sizes, an optional description, start or end label placement for settings lists, and native form submission.

```tsx title="switch/demo.tsx"
"use client";

import { Switch } from "@/components/ui/switch";

export default function SwitchDemo() {
  return <Switch defaultSelected>Airplane mode</Switch>;
}
```

## Installation

```bash
npx shadcn@latest add @desyne/switch
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { Switch } from "@/components/ui/switch";
```

```tsx
<Switch isSelected={wifi} onChange={setWifi}>
  Wi-Fi
</Switch>
```

<Callout title="Switches apply immediately">
  Users expect a switch to take effect the moment it's flipped, like a light
  switch. If the change only applies after pressing Save or Submit, use a
  [Checkbox](/docs/components/checkbox) instead.
</Callout>

### When to use

* Switch — a single on/off setting that applies right away: notifications, dark mode, a feature flag.
* [Checkbox](/docs/components/checkbox) — options confirmed by a submit button, required consent, or many options in a group.
* [Toggle Button](/docs/components/toggle-button) — an on/off state inside a toolbar, like bold or mute.
* [Radio Group](/docs/components/radio-group) — more than two states, or two states whose labels aren't simply "on" and "off".

## Anatomy

```tsx
<Switch>      {/* <label> wrapping a hidden <input type="checkbox" role="switch"> */}
  Label       {/* children */}
</Switch>
```

| Part     | Renders                                    | Notes                                                                                     |
| -------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `Switch` | `<label>` + hidden `<input role="switch">` | Root. Carries `data-slot="switch"` and every state attribute.                             |
| Track    | `<span>`                                   | The pill. Uses `--brand` when on. Sized by `size`.                                        |
| Thumb    | `<span>`                                   | The white knob; slides to the end when on.                                                |
| Label    | children                                   | Next to the track. With `description`, becomes a bold title with secondary text under it. |

## Examples

### Sizes

`md` is the default. Use `sm` in dense lists and tables, and `lg` for a prominent master switch or touch-first layouts.

Example `switch/sizes`: source in https://desyne.dev/docs/components/switch.md

### With description

`description` adds secondary text under the label and aligns the track to the first line. Use it to explain what the setting does.

Example `switch/description`: source in https://desyne.dev/docs/components/switch.md

### Label placement

`labelPlacement="start"` puts the label first and pushes the switch to the far end of its container, which is the usual layout for settings rows.

Example `switch/label-placement`: source in https://desyne.dev/docs/components/switch.md

### States

`isDisabled` dims the switch and removes it from the tab order. `isReadOnly` keeps it focusable and announced, but ignores presses, which is useful while a change is saving.

Example `switch/states`: source in https://desyne.dev/docs/components/switch.md

### Controlled

Use `isSelected` and `onChange` to own the value. Use `defaultSelected` when you only need the initial state.

Example `switch/controlled`: source in https://desyne.dev/docs/components/switch.md

### Without a visible label

When the label lives elsewhere in the layout, point to it with `aria-labelledby` (and to helper text with `aria-describedby`). A switch with no label at all needs an `aria-label`.

Example `switch/standalone`: source in https://desyne.dev/docs/components/switch.md

### Settings list

`labelPlacement="start"` plus `description` and some padding turns each switch into a full-width, fully clickable settings row.

Example `switch/settings`: source in https://desyne.dev/docs/components/switch.md

### Revealing options

Control the switch to show dependent fields only when the setting is on.

Example `switch/reveal`: source in https://desyne.dev/docs/components/switch.md

### Saving asynchronously

Because switches apply immediately, persist the change right away. Update optimistically, set `isReadOnly` while the request is in flight, and roll back with a message if it fails. The status text is in an `aria-live` region so screen-reader users hear the outcome.

Example `switch/async`: source in https://desyne.dev/docs/components/switch.md

### Form submission

Give the switch a `name` and its `value` (`"on"` by default) is submitted when it's on. Like a native checkbox, nothing is submitted when it's off, so treat a missing key as false on the server.

Example `switch/form`: source in https://desyne.dev/docs/components/switch.md

`Switch` doesn't support `isRequired` or validation. For a required "I agree" control, use a [Checkbox](/docs/components/checkbox#required-and-validation).

## Recipes

### Notification settings

A large master switch that disables and clears the category switches under it.

Example `switch/recipe-notifications`: source in https://desyne.dev/docs/components/switch.md

### Feature flags

Small switches aligned to the end of each row, labelled by the flag name via `aria-labelledby`, with a [`Badge`](/docs/components/badge) for the release stage.

Example `switch/recipe-feature-flags`: source in https://desyne.dev/docs/components/switch.md

### Billing period toggle

A switch that flips pricing cards between monthly and yearly billing.

Example `switch/recipe-billing-toggle`: source in https://desyne.dev/docs/components/switch.md

## Accessibility

* Renders a native `<input type="checkbox" role="switch">`, visually hidden inside a `<label>`, so screen readers announce it as a switch that is on or off, and clicking the label toggles it.
* Keep the label constant (e.g. "Wi-Fi"), not "Turn on Wi-Fi" / "Turn off Wi-Fi": the on/off state is announced separately.
* A switch without children needs `aria-label` or `aria-labelledby`.
* `description` is rendered inside the `<label>`, so it's read as part of the name. For long help text, render it outside and link it with `aria-describedby`.
* If a change can fail or takes time, announce the outcome in an `aria-live` region.
* The focus ring only appears for keyboard focus (`data-focus-visible`).

### Keyboard

| Key              | Action                    |
| ---------------- | ------------------------- |
| <kbd>Tab</kbd>   | Moves focus to the switch |
| <kbd>Space</kbd> | Toggles the switch        |

## Styling

### Data attributes

On the `Switch` root (target the track or thumb with `group-data-*/switch:`):

| Attribute                             | Present when                        |
| ------------------------------------- | ----------------------------------- |
| `data-selected`                       | On                                  |
| `data-hovered`                        | Hovered with a mouse or pen         |
| `data-pressed`                        | Being pressed                       |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard |
| `data-disabled`                       | `isDisabled` is true                |
| `data-readonly`                       | `isReadOnly` is true                |

### Slots

| `data-slot` | Element                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `switch`    | The `<label>` root. Target switches from a parent with `*:data-[slot=switch]:…` |

### Color

The track uses the `--brand` theme variable when on. Override it for a one-off color:

```tsx
<Switch className="[--brand:var(--color-emerald-600)]">Online</Switch>
```

### Render props

`className` and `children` accept a function of the switch state:

```tsx
<Switch>{({ isSelected }) => (isSelected ? "Visible to everyone" : "Hidden")}</Switch>
```

## API Reference

### Switch

<TypeTable
  type="{
  children: { type: &#x22;ReactNode | ((state: SwitchRenderProps) => ReactNode)&#x22;, description: &#x22;The label.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Secondary text under the label. Makes the label bold and aligns the track to the first line.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Track and thumb size.&#x22; },
  labelPlacement: { type: '&#x22;end&#x22; | &#x22;start&#x22;', default: '&#x22;end&#x22;', description: &#x22;start puts the label first and spreads the row (justify-between).&#x22; },
  isSelected: { type: &#x22;boolean&#x22;, description: &#x22;Controlled on state.&#x22; },
  defaultSelected: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial on state.&#x22; },
  onChange: { type: &#x22;(isSelected: boolean) => void&#x22;, description: &#x22;Called when the state changes.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the switch and removes it from the tab order.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Focusable but can't be changed.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  value: { type: &#x22;string&#x22;, description: &#x22;Value submitted when on. Defaults to \&#x22;on\&#x22; natively.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the input belongs to.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  inputRef: { type: &#x22;Ref<HTMLInputElement>&#x22;, description: &#x22;Ref to the hidden input.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;onPressStart, onPressEnd, onPressChange and onPressUp are also supported.&#x22; },
  onHoverChange: { type: &#x22;(isHovered: boolean) => void&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22;, description: &#x22;onBlur and onFocusChange are also supported.&#x22; },
  className: { type: &#x22;string | ((state: SwitchRenderProps) => string)&#x22;, description: &#x22;Classes for the <label> root.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there are no children.&#x22; },
  &#x22;aria-controls&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of the element the switch controls.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Switch`](https://react-aria.adobe.com/Switch#api).

## Related

* [Checkbox](/docs/components/checkbox) — for options confirmed with a submit button.
* [Toggle Button](/docs/components/toggle-button) — an on/off button for toolbars.
* [Radio Group](/docs/components/radio-group) — for more than two states.

---

# Slider

Source: https://desyne.dev/docs/components/slider

> Lets users pick a number, or a range between two numbers, by dragging a thumb along a track. Locale-aware value formatting, steps, tick marks, seven color tones and two sizes, with full keyboard support.

```tsx title="slider/demo.tsx"
"use client";

import { Slider } from "@/components/ui/slider";

export default function SliderDemo() {
  return <Slider className="max-w-xs" label="Volume" defaultValue={60} />;
}
```

## Installation

```bash
npx shadcn@latest add @desyne/slider
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { Slider } from "@/components/ui/slider";
```

```tsx
<Slider label="Volume" defaultValue={60} />

<Slider label="Price" defaultValue={[200, 800]} maxValue={1000} />
```

Pass a number for a single thumb, or an array for one thumb per value. The type of `value`, `defaultValue` and `onChange` follows whichever you pass.

### When to use

* Slider — an approximate value within a known range where relative position matters more than precision: volume, opacity, a price range.
* [Number Field](/docs/components/number-field) — an exact number, or a range too large to drag through. Pair the two when users need both ([example](#with-a-number-field)).
* [Radio Group](/docs/components/radio-group) or [Select](/docs/components/select) — a handful of discrete, named options rather than a continuous scale.
* [Progress Bar](/docs/components/progress-bar) or [Meter](/docs/components/meter) — displaying a value users can't change.

## Anatomy

```tsx
<Slider>        {/* root: label, output, track, marks */}
  Label         {/* from `label` */}
  Output        {/* formatted value, from `showOutput` */}
  Track         {/* background, filled range and one thumb per value */}
  Marks         {/* from `marks` */}
</Slider>
```

| Part     | Renders                                 | Notes                                                                                                                                 |
| -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Slider` | `<div role="group">`                    | Root. Sets the tone variables from `color`.                                                                                           |
| Label    | `<label>`                               | Rendered from `label`.                                                                                                                |
| Output   | `<output>`                              | Current value(s), formatted with `formatOptions`. Two values are formatted as a locale-aware range. Hidden with `showOutput={false}`. |
| Track    | `<div>`                                 | Muted background plus a filled segment from the start (or between two thumbs).                                                        |
| Thumb    | `<div>` + hidden `<input type="range">` | One per value. Grows a soft ring on hover, focus and drag.                                                                            |
| Marks    | `<div aria-hidden>`                     | Numeric labels positioned along the track from `marks`. Hidden from screen readers, which announce the thumb's value instead.         |

## Examples

### Range

Pass an array to `defaultValue` (or `value`) for two thumbs. The fill spans between them, and thumbs can't cross each other. Each thumb gets its own accessible label: two-thumb sliders default to "Minimum" and "Maximum", and `thumbLabels` sets your own (e.g. `["Start", "End"]`).

Example `slider/range`: source in https://desyne.dev/docs/components/slider.md

### Step, min and max

`minValue` and `maxValue` default to 0 and 100, and `step` to 1. Values snap to the step while dragging and with the keyboard.

Example `slider/step`: source in https://desyne.dev/docs/components/slider.md

### Value formatting

`formatOptions` takes any `Intl.NumberFormat` options. The output and the value screen readers announce are both formatted in the user's locale: percentages, currencies and units.

Example `slider/formatting`: source in https://desyne.dev/docs/components/slider.md

### Fill offset

By default the fill starts at `minValue`. For a single thumb, `fillOffset` starts it from another value instead, such as 0 on a -12 to 12 scale, so the fill grows in either direction. The equalizer in the next example uses `fillOffset={0}`.

### Vertical

`orientation="vertical"` stacks the label and output above a vertical track. Marks sit beside the track. A vertical slider is `h-48` by default; set a height with `className` (e.g. `h-56`). Sizes, colors, ranges and marks all work the same way. Up and down arrows move the thumb.

Example `slider/vertical`: source in https://desyne.dev/docs/components/slider.md

### Marks

`marks` renders labels under the track at the given values. Match them to `step` so every mark is reachable. Marks show raw numbers; they don't use `formatOptions`.

Example `slider/marks`: source in https://desyne.dev/docs/components/slider.md

### Colors

`color` accepts any tone and defaults to `brand`. Use `neutral` for media controls and `danger` or `warning` only when the value itself signals risk.

Example `slider/colors`: source in https://desyne.dev/docs/components/slider.md

### Sizes

`md` is the default. `sm` has a thinner track and a smaller thumb for dense panels.

Example `slider/sizes`: source in https://desyne.dev/docs/components/slider.md

### With icons, no visible label

Set `showOutput={false}` and put icons on either side for a compact control. Without a `label`, an `aria-label` is required.

Example `slider/with-icons`: source in https://desyne.dev/docs/components/slider.md

### Disabled

`isDisabled` dims the slider and removes every thumb from the tab order.

Example `slider/disabled`: source in https://desyne.dev/docs/components/slider.md

### Controlled

`onChange` fires continuously while dragging; `onChangeEnd` fires once when the user lets go (or after each key press). Update the UI with the first and save or fetch with the second.

Example `slider/controlled`: source in https://desyne.dev/docs/components/slider.md

### With a number field

Share one state between a slider and a [`NumberField`](/docs/components/number-field) so users can drag for speed or type for precision.

Example `slider/with-input`: source in https://desyne.dev/docs/components/slider.md

### Form submission

Pass `name` and each thumb's hidden range input is submitted with the form. For a range, a string names every thumb, so read it with `formData.getAll(name)`; an array such as `["ageMin", "ageMax"]` names each thumb separately. `form` associates the inputs with a `<form>` elsewhere in the document by id. A disabled slider is not submitted.

Example `slider/form`: source in https://desyne.dev/docs/components/slider.md

## Recipes

### Price filter

A range slider kept in sync with two number fields, with a live result count.

Example `slider/recipe-price-filter`: source in https://desyne.dev/docs/components/slider.md

### Image adjustments

Small neutral sliders driving CSS filters on a preview, with a reset.

Example `slider/recipe-image-adjust`: source in https://desyne.dev/docs/components/slider.md

### Pricing calculator

Two sliders feeding a live monthly estimate, one with `marks` and one formatted in gigabytes.

Example `slider/recipe-pricing-calculator`: source in https://desyne.dev/docs/components/slider.md

## Accessibility

* Each thumb contains a visually hidden `<input type="range">`, so screen readers announce it as a slider with its label, current value, minimum and maximum.
* The announced value uses `formatOptions` (e.g. "80%", "€2,500"), and the visible output is an `<output>` element linked to the thumbs.
* Without a `label`, pass `aria-label` or `aria-labelledby`.
* In a range, each thumb input has its thumb label as `aria-label`, combined with the slider label through `aria-labelledby`, so screen readers can tell the thumbs apart. Override the defaults with `thumbLabels`.
* Clicking anywhere on the track moves the nearest thumb there; thumbs can also be dragged with mouse, touch or pen.
* In right-to-left locales the track direction and arrow keys are mirrored.
* The focus ring only appears for keyboard focus (`data-focus-visible`).

### Keyboard

| Key                                       | Action                                 |
| ----------------------------------------- | -------------------------------------- |
| <kbd>Tab</kbd>                            | Moves focus to the next thumb          |
| <kbd>→</kbd> / <kbd>↑</kbd>               | Increases the value by one step        |
| <kbd>←</kbd> / <kbd>↓</kbd>               | Decreases the value by one step        |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | Increases / decreases by a larger step |
| <kbd>Home</kbd> / <kbd>End</kbd>          | Sets the minimum / maximum value       |

## Styling

### Data attributes

On the `Slider` root:

| Attribute          | Present when                   |
| ------------------ | ------------------------------ |
| `data-disabled`    | `isDisabled` is true           |
| `data-orientation` | `"horizontal"` or `"vertical"` |

On each thumb (style them from the root with arbitrary variants such as `[&_[data-dragging]]:…`):

| Attribute                             | Present when                        |
| ------------------------------------- | ----------------------------------- |
| `data-dragging`                       | Being dragged                       |
| `data-hovered`                        | Hovered with a mouse or pen         |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard |
| `data-disabled`                       | The slider is disabled              |

### Slots

| `data-slot`    | Element                           |
| -------------- | --------------------------------- |
| `slider`       | Root                              |
| `label`        | The label                         |
| `slider-track` | The track (click and drag target) |
| `slider-fill`  | The filled segment                |
| `slider-thumb` | Each thumb                        |

### Tone variables

`color` sets `--tone` on the root. The filled track, the thumb border and its ring all use it, so a one-off color is a single class:

```tsx
<Slider label="Heat" className="[--tone:var(--color-orange-500)]" defaultValue={70} />
```

### Render props

`className` accepts a function of the slider state (`orientation`, `isDisabled`, `state`):

```tsx
<Slider className={({ isDisabled }) => (isDisabled ? "grayscale" : "")} />
```

## API Reference

### Slider

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  showOutput: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the formatted value next to the label.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', default: '&#x22;brand&#x22;', description: &#x22;Tone of the fill and thumbs.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Track thickness and thumb size.&#x22; },
  marks: { type: &#x22;number[]&#x22;, description: &#x22;Values to label along the track, e.g. [0, 25, 50, 75, 100].&#x22; },
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Vertical sliders default to h-48; set a height with className.&#x22; },
  name: { type: &#x22;string | string[]&#x22;, description: &#x22;Form name. A string names every thumb; an array names each thumb by index.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the thumbs' inputs belong to.&#x22; },
  thumbLabels: { type: &#x22;string[]&#x22;, description: 'Accessible label for each thumb, by index. Two-thumb sliders default to [&#x22;Minimum&#x22;, &#x22;Maximum&#x22;].' },
  fillOffset: { type: &#x22;number&#x22;, description: &#x22;For a single thumb, the value the fill starts from. Defaults to minValue.&#x22; },
  value: { type: &#x22;number | number[]&#x22;, description: &#x22;Controlled value. An array renders one thumb per item.&#x22; },
  defaultValue: { type: &#x22;number | number[]&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: T) => void&#x22;, description: &#x22;Called continuously while the value changes.&#x22; },
  onChangeEnd: { type: &#x22;(value: T) => void&#x22;, description: &#x22;Called when the user stops dragging or releases a key.&#x22; },
  minValue: { type: &#x22;number&#x22;, default: &#x22;0&#x22; },
  maxValue: { type: &#x22;number&#x22;, default: &#x22;100&#x22; },
  step: { type: &#x22;number&#x22;, default: &#x22;1&#x22;, description: &#x22;Increment between values.&#x22; },
  formatOptions: { type: &#x22;Intl.NumberFormatOptions&#x22;, description: &#x22;Formats the output and the announced value.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  id: { type: &#x22;string&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there's no visible label.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22; },
  className: { type: &#x22;string | ((state: SliderRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Slider`](https://react-aria.adobe.com/Slider#api).

## Related

* [Number Field](/docs/components/number-field) — for exact numeric input.
* [Progress Bar](/docs/components/progress-bar) — shares the same tones, for read-only progress.
* [Color Picker](/docs/components/color-picker) — includes a `ColorSlider` for color channels.

---

# Input OTP

Source: https://desyne.dev/docs/components/input-otp

> A one-time code input split into individual character slots. Backed by a single real input, so paste, SMS and password-manager autofill, and screen readers work. Supports digit or alphanumeric patterns, grouped or separated slots, auto-verify on complete, invalid states and form submission.

```tsx title="input-otp/demo.tsx"
"use client";

import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@/components/ui/input-otp";

export default function InputOTPDemo() {
  return (
    <InputOTP maxLength={6} aria-label="One-time code">
      <InputOTPGroup>
        <InputOTPSlot index={0} />
        <InputOTPSlot index={1} />
        <InputOTPSlot index={2} />
      </InputOTPGroup>
      <InputOTPSeparator />
      <InputOTPGroup>
        <InputOTPSlot index={3} />
        <InputOTPSlot index={4} />
        <InputOTPSlot index={5} />
      </InputOTPGroup>
    </InputOTP>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/input-otp
```

npm dependencies (installed by the CLI): input-otp, lucide-react.

## Usage

```tsx
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from "@/components/ui/input-otp";
```

```tsx
<InputOTP maxLength={6} aria-label="Verification code">
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>
```

`InputOTP` wraps the [`input-otp`](https://input-otp.rodz.dev) package. It renders one transparent `<input>` stretched over the slots; the slots only display what's typed, reading each character and the caret position from context. Render one `InputOTPSlot` per character, with `index` from `0` to `maxLength - 1`.

<Callout title="Not a React Aria component">
  Unlike the other fields, `InputOTP` takes native input props such as
  `disabled` and `required`, not `isDisabled` or `isRequired`. Its `onChange`
  receives the new value as a string. The caret needs the `animate-caret-blink`
  keyframes, which the registry adds to your CSS on install.
</Callout>

### When to use

* Input OTP — short verification codes of a fixed length: email or SMS codes, authenticator (TOTP) codes, PINs, recovery codes.
* [Text Field](/docs/components/text-field) — codes of variable length, or when you'd rather show a single box (`inputMode="numeric"`, `autoComplete="one-time-code"`).
* [Number Field](/docs/components/number-field) — actual quantities. Codes aren't numbers: leading zeros matter.

## Anatomy

```tsx
<InputOTP>                 {/* container <div> + one real <input> */}
  <InputOTPGroup>          {/* joined or separated set of slots */}
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
  </InputOTPGroup>
  <InputOTPSeparator />    {/* optional visual divider */}
  <InputOTPGroup>…</InputOTPGroup>
</InputOTP>
```

| Part                | Renders                  | Notes                                                                                                                                                                                 |
| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InputOTP`          | `<div>` + `<input>`      | The container (`containerClassName`) is a flex row with a gap and dims when the input is disabled. The input (`className`, `data-slot="input-otp"`) receives every native input prop. |
| `InputOTPGroup`     | `<div>`                  | `variant="joined"` (default) draws slots as one segmented box; `separated` draws individual boxes with a gap.                                                                         |
| `InputOTPSlot`      | `<div>`                  | Displays the character at `index`, a blinking fake caret when it's the active empty slot, and a focus ring while active.                                                              |
| `InputOTPSeparator` | `<div role="separator">` | A muted minus icon between groups. Purely visual.                                                                                                                                     |

## Examples

### Separated slots

`variant="separated"` on `InputOTPGroup` renders each slot as its own rounded box. Joined slots read as one field; separated slots suit larger, touch-first layouts.

Example `input-otp/separated`: source in https://desyne.dev/docs/components/input-otp.md

### Digits only

`pattern` takes a regex source string; characters and pastes that don't match are rejected. The package exports `REGEXP_ONLY_DIGITS`, `REGEXP_ONLY_CHARS` and `REGEXP_ONLY_DIGITS_AND_CHARS`. The mobile keyboard is numeric by default (`inputMode="numeric"`).

Example `input-otp/digits-only`: source in https://desyne.dev/docs/components/input-otp.md

### Alphanumeric codes

For recovery or invite codes, allow letters with `REGEXP_ONLY_DIGITS_AND_CHARS`, switch to `inputMode="text"`, and use `pasteTransformer` to strip spaces or dashes from pasted codes. `uppercase` on the slots displays letters in capitals; the value keeps the case the user typed.

Example `input-otp/alphanumeric`: source in https://desyne.dev/docs/components/input-otp.md

### Sizes

Slots are 40px squares by default. Resize them with `className` on each `InputOTPSlot` (`size-*` and a text size), and adjust the group's gap for separated slots.

Example `input-otp/sizes`: source in https://desyne.dev/docs/components/input-otp.md

### Placeholder

`placeholder` on `InputOTP` is split across the slots: slot `n` shows character `n` in a muted color. As in input-otp itself, the placeholder is shown only while the whole input is empty, and it's hidden in the slot that has the blinking caret. The string is also exposed to screen readers as `aria-placeholder` on the input.

Example `input-otp/placeholder`: source in https://desyne.dev/docs/components/input-otp.md

### Controlled

`value` and `onChange` hold the code as a string. Set it to `""` to clear.

Example `input-otp/controlled`: source in https://desyne.dev/docs/components/input-otp.md

### Verify on complete

`onComplete` fires with the full code when the last slot is filled, so users don't need a submit button. Disable the input while you check it, and announce the result in an `aria-live` region.

Example `input-otp/on-complete`: source in https://desyne.dev/docs/components/input-otp.md

### Invalid

Slots turn red when they carry `aria-invalid`. Set it on each `InputOTPSlot` for the visual state, and on `InputOTP` (with `aria-describedby` pointing at the message) so screen readers hear it.

Example `input-otp/invalid`: source in https://desyne.dev/docs/components/input-otp.md

### Disabled

`disabled` disables the input; the container dims through `has-disabled:opacity-50`.

Example `input-otp/disabled`: source in https://desyne.dev/docs/components/input-otp.md

### Form submission

The real input submits under its `name`. Use `required` and `minLength` equal to `maxLength` for native validation, and link a visible `<label>` with `id` / `htmlFor`.

Example `input-otp/form`: source in https://desyne.dev/docs/components/input-otp.md

## Recipes

### Verify email

A verification card: the heading labels the input through `aria-labelledby`, submit stays disabled until all six digits are in, and a resend link has a cooldown.

Example `input-otp/recipe-verify-email`: source in https://desyne.dev/docs/components/input-otp.md

### Two-factor sign-in

Authenticator codes with a switch to 10-character recovery codes. Changing mode remounts the input (`key`) with a new `maxLength`, `pattern` and `inputMode`; a wrong code marks the slots invalid.

Example `input-otp/recipe-two-factor`: source in https://desyne.dev/docs/components/input-otp.md

## Accessibility

* A single native `<input>` holds the value, so screen readers announce one text field, and paste, SMS one-time-code autofill (`autoComplete="one-time-code"` is the default) and password managers work.
* Always provide a label: `aria-label`, `aria-labelledby`, or a `<label htmlFor>` pointing at the input's `id`. The slots are visual only.
* The separator has `role="separator"` and a decorative icon.
* Announce verification results and errors with `aria-live`, and set `aria-invalid` plus `aria-describedby` on `InputOTP` for invalid codes; the slot styling alone isn't announced.
* Prefer `onComplete` for auto-verify, but keep a way to retry and don't clear the code without telling the user.

### Keyboard

| Key                                           | Action                                                             |
| --------------------------------------------- | ------------------------------------------------------------------ |
| Typing                                        | Fills the active slot and moves to the next one                    |
| <kbd>Backspace</kbd>                          | Deletes the previous character                                     |
| <kbd>←</kbd> / <kbd>→</kbd>                   | Moves the caret between slots                                      |
| <kbd>⌘</kbd> / <kbd>Ctrl</kbd> + <kbd>V</kbd> | Pastes a whole code, after `pasteTransformer` and `pattern` checks |

## Styling

### Data attributes

| Attribute                  | Element         | Present when                                                      |
| -------------------------- | --------------- | ----------------------------------------------------------------- |
| `data-active="true"`       | `InputOTPSlot`  | The caret or selection is on this slot while the input is focused |
| `data-placeholder`         | `InputOTPSlot`  | The slot is showing its placeholder character                     |
| `aria-invalid`             | `InputOTPSlot`  | You pass it; draws a destructive border                           |
| `data-variant`             | `InputOTPGroup` | Always: `joined` or `separated`                                   |
| `data-input-otp-container` | Container       | Always (set by the package)                                       |

Slots read their group's variant through `group/otp`, so `group-data-[variant=separated]/otp:` targets separated slots from your own classes.

### Slots

| `data-slot`           | Element            |
| --------------------- | ------------------ |
| `input-otp`           | The real `<input>` |
| `input-otp-group`     | Group              |
| `input-otp-slot`      | Slot               |
| `input-otp-separator` | Separator          |

`containerClassName` styles the row around the slots; `className` styles the transparent input itself. The fake caret uses the `animate-caret-blink` utility.

## API Reference

### InputOTP

<TypeTable
  type="{
  maxLength: { type: &#x22;number&#x22;, description: &#x22;Required. Number of characters (and slots).&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Groups, slots and separators. Required unless you pass render.&#x22; },
  value: { type: &#x22;string&#x22;, description: &#x22;Controlled value.&#x22; },
  defaultValue: { type: &#x22;string&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called with the new value (a string, not an event).&#x22; },
  onComplete: { type: &#x22;(value: string) => void&#x22;, description: &#x22;Called when all slots are filled.&#x22; },
  pattern: { type: &#x22;string&#x22;, description: &#x22;Regex source every character must match, e.g. REGEXP_ONLY_DIGITS.&#x22; },
  pasteTransformer: { type: &#x22;(pasted: string) => string&#x22;, description: &#x22;Cleans pasted text before it is checked and inserted.&#x22; },
  placeholder: { type: &#x22;string&#x22;, description: &#x22;One character per slot, shown muted in the slots while the input is empty.&#x22; },
  inputMode: { type: '&#x22;numeric&#x22; | &#x22;text&#x22; | &#x22;decimal&#x22; | &#x22;tel&#x22; | …', default: '&#x22;numeric&#x22;', description: &#x22;Virtual keyboard hint.&#x22; },
  autoComplete: { type: &#x22;string&#x22;, default: '&#x22;one-time-code&#x22;', description: &#x22;Autofill hint; the default enables SMS code autofill.&#x22; },
  textAlign: { type: '&#x22;left&#x22; | &#x22;center&#x22; | &#x22;right&#x22;', default: '&#x22;left&#x22;', description: &#x22;Where the caret sits in the hidden input.&#x22; },
  pushPasswordManagerStrategy: { type: '&#x22;increase-width&#x22; | &#x22;none&#x22;', default: '&#x22;increase-width&#x22;', description: &#x22;Widens the input so password-manager badges don't cover the last slot.&#x22; },
  containerClassName: { type: &#x22;string&#x22;, description: &#x22;Classes for the container row.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the transparent input.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  required: { type: &#x22;boolean&#x22;, description: &#x22;Native required constraint.&#x22; },
  minLength: { type: &#x22;number&#x22;, description: &#x22;Native minimum length; set it to maxLength to require a full code.&#x22; },
  disabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables the input and dims the slots.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22; },
  id: { type: &#x22;string&#x22;, description: &#x22;Id of the input, for a <label htmlFor>.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22; },
  &#x22;aria-invalid&#x22;: { type: &#x22;boolean&#x22;, description: &#x22;Announces the code as invalid. Pair with aria-describedby.&#x22; },
  render: { type: &#x22;(props: RenderProps) => ReactNode&#x22;, description: &#x22;Alternative to children: render slots from { slots, isFocused, isHovering }.&#x22; },
}"
/>

Also accepts every native `<input>` attribute. See the [input-otp docs](https://input-otp.rodz.dev) for the full API.

### InputOTPGroup

<TypeTable
  type="{
  variant: { type: '&#x22;joined&#x22; | &#x22;separated&#x22;', default: '&#x22;joined&#x22;', description: &#x22;joined slots share borders; separated slots are individual boxes.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every `<div>` prop.

### InputOTPSlot

<TypeTable
  type="{
  index: { type: &#x22;number&#x22;, description: &#x22;Required. Position of the character this slot displays, from 0.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Resize or restyle the slot, e.g. size-12 text-xl.&#x22; },
  &#x22;aria-invalid&#x22;: { type: &#x22;boolean&#x22;, description: &#x22;Draws the destructive border.&#x22; },
}"
/>

Also accepts every `<div>` prop. While the input is empty, the slot renders its character of the input's `placeholder` (muted, `aria-hidden`).

### InputOTPSeparator

Accepts every `<div>` prop. Renders `role="separator"` with a minus icon.

## Related

* [Text Field](/docs/components/text-field) — for codes of variable length.
* [Number Field](/docs/components/number-field) — for real numbers.
* [Dialog](/docs/components/dialog) — a common home for verification steps.

---

# Color Picker

Source: https://desyne.dev/docs/components/color-picker

> A ready-made swatch button that opens a saturation/brightness area, hue slider, hex field and presets in a popover, plus every building block (ColorArea, ColorSlider, ColorField, ColorSwatch, ColorSwatchPicker) to compose your own inline or popover editors.

```tsx title="color-picker/demo.tsx"
"use client";

import { ColorPicker } from "@/components/ui/color-picker";

export default function ColorPickerDemo() {
  return (
    <ColorPicker
      label="Brand color"
      defaultValue="#6366f1"
      swatches={[
        "#ef4444",
        "#f97316",
        "#eab308",
        "#22c55e",
        "#06b6d4",
        "#3b82f6",
        "#6366f1",
        "#a855f7",
      ]}
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/color-picker
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { ColorPicker } from "@/components/ui/color-picker";
```

```tsx
<ColorPicker label="Accent" defaultValue="#6366f1" swatches={["#ef4444", "#22c55e"]} />
```

`ColorPicker` is a complete control. For a custom popover, pass the parts as `children`. For an inline editor, wrap the parts in React Aria's `ColorPicker`, which keeps one shared color in sync between them:

```tsx
import { ColorPicker as ColorPickerState } from "react-aria-components";
import { ColorArea, ColorField, ColorSlider } from "@/components/ui/color-picker";

<ColorPickerState defaultValue="#6366f1">
  <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness" />
  <ColorSlider label="Hue" colorSpace="hsb" channel="hue" />
  <ColorField label="Hex" />
</ColorPickerState>;
```

Values can be passed as any CSS color string (`"#6366f1"`, `"rgb(…)"`, `"hsl(…)"`) or a `Color` object from `parseColor`. `onChange` always receives a `Color`; call `color.toString("hex")` (or `"rgb"`, `"hsl"`, `"css"`…) to serialize it.

### When to use

* Color Picker — any color, when users need precise control or a custom brand color.
* [`ColorSwatchPicker`](#swatch-picker) on its own — a fixed palette, such as label or calendar colors. Faster and keeps colors consistent.
* [`ColorField`](#color-field) — users who already know the hex value, like designers pasting from a design tool.
* [`ColorSwatch`](#swatches) — displaying a color that isn't editable.

## Anatomy

```tsx
<ColorPicker>                 {/* trigger button + popover dialog */}
  <ColorArea />               {/* 2D saturation × brightness, with a ColorThumb */}
  <ColorSlider />             {/* one channel: hue, alpha, red… */}
  <ColorField />              {/* hex or single-channel text input */}
  <ColorSwatchPicker>         {/* preset list */}
    <ColorSwatchPickerItem /> {/* one preset, renders a ColorSwatch */}
  </ColorSwatchPicker>
</ColorPicker>
```

| Part                    | Renders                                     | Notes                                                                                                                                                     |
| ----------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ColorPicker`           | `<button>` + popover `role="dialog"`        | Outline button with a swatch and `label`. The dialog holds the default editor, or your `children`. With `name`, also a hidden `<input>` after the button. |
| `ColorArea`             | `<div>` + two hidden `<input type="range">` | Drags two channels at once. Defaults to 192px square; add `w-full` to fill its container.                                                                 |
| `ColorSlider`           | `<div role="group">`                        | Label and value output (when `label` is set) above a 12px gradient track.                                                                                 |
| `ColorThumb`            | `<div>`                                     | The white ring handle used by `ColorArea` and `ColorSlider`. Exported for custom compositions.                                                            |
| `ColorField`            | `<div>` + `<input>`                         | Monospace text input with optional `label`, `description` and error.                                                                                      |
| `ColorSwatch`           | `<div role="img">`                          | A static color preview, labelled with a human-readable color name.                                                                                        |
| `ColorSwatchPicker`     | `<div role="listbox">`                      | A wrapping row of selectable presets.                                                                                                                     |
| `ColorSwatchPickerItem` | `<div role="option">`                       | One preset; shows a ring when hovered, focused or selected.                                                                                               |

## Examples

### Controlled

Pass a `Color` as `value` and update it in `onChange`. Keep the `Color` object in state and serialize it only when you need a string.

Example `color-picker/controlled`: source in https://desyne.dev/docs/components/color-picker.md

### Custom popover content

`children` replace the default popover content. Here an alpha slider is added so users can pick translucent colors; the parts inside still share the picker's value.

Example `color-picker/custom-content`: source in https://desyne.dev/docs/components/color-picker.md

### Inline editor

The same parts without a popover, wrapped in React Aria's `ColorPicker`. Use it in sidebars and design tools where the editor is always visible.

Example `color-picker/area-slider`: source in https://desyne.dev/docs/components/color-picker.md

### Channel sliders

`ColorSlider` edits one `channel` in a `colorSpace`: `rgb` (red, green, blue), `hsl` (hue, saturation, lightness), `hsb` (hue, saturation, brightness), plus `alpha`. The track previews the gradient for that channel.

Example `color-picker/channel-sliders`: source in https://desyne.dev/docs/components/color-picker.md

### Channel fields

A `ColorField` with a `channel` edits a single number instead of the hex string, so users can type exact RGB or HSL values.

Example `color-picker/channel-fields`: source in https://desyne.dev/docs/components/color-picker.md

### Color field

A standalone hex input. The value is parsed when the user presses <kbd>Enter</kbd> or leaves the field, and arrow keys step it. `isInvalid` with `errorMessage` shows your own validation, such as a contrast check.

Example `color-picker/color-field`: source in https://desyne.dev/docs/components/color-picker.md

### Swatch picker

`ColorSwatchPicker` is a single-select list of presets with its own `value`, `defaultValue` and `onChange`. Give it an `aria-label` describing what the color is for.

Example `color-picker/swatches`: source in https://desyne.dev/docs/components/color-picker.md

### Swatches

`ColorSwatch` displays a color. It's announced by its color name (e.g. "dark vibrant blue"); pass `colorName` to use your own palette's name instead.

Example `color-picker/swatch`: source in https://desyne.dev/docs/components/color-picker.md

### Disabled and read-only

`isDisabled` on `ColorPicker` disables the trigger, keeps the popover closed and leaves its value out of form submissions. On `ColorArea` and `ColorSlider` it dims them and removes them from the tab order. `ColorField` supports both `isDisabled` and `isReadOnly`.

Example `color-picker/disabled`: source in https://desyne.dev/docs/components/color-picker.md

### Form submission

`ColorField` takes a `name` and submits its hex value. `ColorPicker` takes a `name` too: it renders a hidden input next to the trigger, inside your form, so it submits even though the editor lives in a popover. The value is an uppercase `#RRGGBB` hex string by default; `valueFormat` picks another format, such as `"hexa"` to keep alpha or `"rgb"` / `"hsl"` / `"css"`. `form` associates the input with a `<form>` by id.

Example `color-picker/form`: source in https://desyne.dev/docs/components/color-picker.md

## Recipes

### Theme editor

A brand color applied live to buttons and badges through the `--tone` and `--tone-fg` variables, with a readable foreground picked automatically.

Example `color-picker/recipe-theme-editor`: source in https://desyne.dev/docs/components/color-picker.md

### Label editor

A name field and a palette of presets, with a live preview of the resulting label.

Example `color-picker/recipe-label-editor`: source in https://desyne.dev/docs/components/color-picker.md

### Gradient builder

Two pickers and a [`Slider`](/docs/components/slider) for the angle, producing copyable CSS.

Example `color-picker/recipe-gradient`: source in https://desyne.dev/docs/components/color-picker.md

## Accessibility

* The `ColorPicker` trigger is a button; the popover is a labelled dialog (named by `label`, then `aria-label`, or "Color picker") that traps focus, closes on <kbd>Esc</kbd> and returns focus to the trigger.
* The default editor's preset list is labelled "Presets".
* `ColorArea` exposes two visually hidden range inputs, one per channel, announced as a two-dimensional slider. Values are announced with the color's name, like "vibrant purple".
* `ColorSlider` is a native range input announced with its channel name and value. Without a `label` it's labelled by the channel name; pass `aria-label` to override it.
* `ColorField` without a visible `label` needs an `aria-label` (the default popover uses "Hex").
* `ColorSwatchPicker` is a listbox: one tab stop, arrow keys to move, and each option announced by color name.
* Don't rely on color alone to convey meaning in what users build with the picked color; check contrast when a color is used for text.

### Keyboard

| Key                                                       | Action                                                                                                       |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| <kbd>Tab</kbd>                                            | Moves between the trigger, area, sliders, fields and swatches                                                |
| <kbd>Enter</kbd> / <kbd>Space</kbd>                       | On the trigger: opens the popover. On a swatch: selects it.                                                  |
| <kbd>←</kbd> / <kbd>→</kbd> / <kbd>↑</kbd> / <kbd>↓</kbd> | In the area: adjusts the x / y channel. In a slider: adjusts the channel. In the swatch picker: moves focus. |
| <kbd>Shift</kbd> + arrows                                 | In the area or a slider: adjusts by a larger step                                                            |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                 | Adjusts the area's y channel, or a slider, by a larger step                                                  |
| <kbd>Home</kbd> / <kbd>End</kbd>                          | Adjusts the area's x channel by a larger step; sets a slider to its min / max                                |
| <kbd>↑</kbd> / <kbd>↓</kbd> in a field                    | Steps the value                                                                                              |
| <kbd>Esc</kbd>                                            | Closes the popover                                                                                           |

## Styling

### Data attributes

| Part                    | Attributes                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `ColorArea`             | `data-disabled`                                                                                        |
| `ColorSlider`           | `data-disabled`, `data-orientation`                                                                    |
| `ColorThumb`            | `data-dragging`, `data-hovered`, `data-focused`, `data-focus-visible`, `data-disabled`                 |
| `ColorField`            | `data-disabled`, `data-invalid`, `data-readonly`, `data-required`, `data-channel`                      |
| `ColorSwatchPickerItem` | `data-selected`, `data-hovered`, `data-pressed`, `data-focused`, `data-focus-visible`, `data-disabled` |

The thumb grows while dragging or keyboard-focused (`data-dragging:size-5.5`, `data-focus-visible:size-5.5`).

### Slots

| `data-slot`                                       | Element                                                          |
| ------------------------------------------------- | ---------------------------------------------------------------- |
| `color-area`, `color-slider`, `color-thumb`       | Area, slider and their thumb                                     |
| `color-field`                                     | Field root (`input` on the input itself)                         |
| `color-swatch`                                    | Every swatch, including the trigger's and each preset's          |
| `color-swatch-picker`, `color-swatch-picker-item` | Preset list and items                                            |
| `label`, `description`, `field-error`             | Field and slider text                                            |
| `color-picker-trigger`                            | The `ColorPicker` trigger button (it also has `button`'s styles) |
| `popover`                                         | The `ColorPicker` popover                                        |

### Sizing

`ColorArea` is `size-48` by default; `className="w-full"` makes it fill the popover or its container. `ColorSwatch` is `size-7`; `ColorSwatchPickerItem` always renders a `size-7` swatch. The popover is `13.5rem` wide.

### Render props

Every part's `className` accepts a function of its state, e.g. the swatch picker item's `isSelected` or the thumb's `isDragging`:

```tsx
<ColorSwatchPickerItem
  color="#2563eb"
  className={({ isSelected }) => (isSelected ? "scale-110" : "")}
/>
```

## API Reference

### ColorPicker

<TypeTable
  type="{
  label: { type: &#x22;string&#x22;, description: &#x22;Text in the trigger button, and the popover dialog's accessible name.&#x22; },
  value: { type: &#x22;string | Color&#x22;, description: &#x22;Controlled color.&#x22; },
  defaultValue: { type: &#x22;string | Color&#x22;, description: &#x22;Uncontrolled initial color.&#x22; },
  onChange: { type: &#x22;(value: Color) => void&#x22;, description: &#x22;Called whenever any part changes the color.&#x22; },
  swatches: { type: &#x22;string[]&#x22;, description: &#x22;Preset colors shown under the default editor. Ignored when children are passed.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Replaces the default popover content (area, hue slider, hex field, presets).&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the trigger, keeps the popover closed and excludes the value from forms.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Renders a hidden input with this name next to the trigger.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form the hidden input belongs to.&#x22; },
  valueFormat: { type: '&#x22;hex&#x22; | &#x22;hexa&#x22; | &#x22;rgb&#x22; | &#x22;rgba&#x22; | &#x22;hsl&#x22; | &#x22;hsla&#x22; | &#x22;hsb&#x22; | &#x22;hsba&#x22; | &#x22;css&#x22;', default: '&#x22;hex&#x22;', description: &#x22;Format of the submitted value. hex drops alpha.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Whether the popover is open (controlled).&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Whether the popover is open initially (uncontrolled).&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the popover opens or closes.&#x22; },
  placement: { type: &#x22;Placement&#x22;, default: '&#x22;bottom start&#x22;', description: &#x22;Popover position relative to the trigger.&#x22; },
  className: { type: &#x22;string | ((state: ButtonRenderProps) => string)&#x22;, description: &#x22;Classes for the trigger button.&#x22; },
  id: { type: &#x22;string&#x22;, description: &#x22;Id of the trigger button.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Trigger label when there's no label. Also names the dialog.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Labels the trigger by another element.&#x22; },
  &#x22;aria-describedby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Describes the trigger by another element.&#x22; },
}"
/>

These are the props `ColorPicker` accepts. React Aria's [`ColorPicker`](https://react-aria.adobe.com/ColorPicker#api) is the state provider underneath.

### ColorArea

<TypeTable
  type="{
  colorSpace: { type: '&#x22;rgb&#x22; | &#x22;hsl&#x22; | &#x22;hsb&#x22;', description: &#x22;Color space the channels belong to.&#x22; },
  xChannel: { type: &#x22;ColorChannel&#x22;, description: 'Horizontal channel, e.g. &#x22;saturation&#x22;.' },
  yChannel: { type: &#x22;ColorChannel&#x22;, description: 'Vertical channel, e.g. &#x22;brightness&#x22;.' },
  value: { type: &#x22;string | Color&#x22;, description: &#x22;Controlled color, when not inside a ColorPicker.&#x22; },
  defaultValue: { type: &#x22;string | Color&#x22; },
  onChange: { type: &#x22;(value: Color) => void&#x22;, description: &#x22;Called continuously while dragging.&#x22; },
  onChangeEnd: { type: &#x22;(value: Color) => void&#x22;, description: &#x22;Called when dragging ends.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  xName: { type: &#x22;string&#x22;, description: &#x22;Form name for the x channel input.&#x22; },
  yName: { type: &#x22;string&#x22;, description: &#x22;Form name for the y channel input.&#x22; },
  className: { type: &#x22;string | ((state: ColorAreaRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ColorArea`](https://react-aria.adobe.com/ColorArea#api).

### ColorSlider

<TypeTable
  type="{
  channel: { type: &#x22;ColorChannel&#x22;, description: 'Required. &#x22;hue&#x22;, &#x22;saturation&#x22;, &#x22;brightness&#x22;, &#x22;lightness&#x22;, &#x22;red&#x22;, &#x22;green&#x22;, &#x22;blue&#x22; or &#x22;alpha&#x22;.' },
  colorSpace: { type: '&#x22;rgb&#x22; | &#x22;hsl&#x22; | &#x22;hsb&#x22;', description: &#x22;Color space the channel belongs to.&#x22; },
  label: { type: &#x22;string&#x22;, description: &#x22;Visible label. Also shows the formatted channel value.&#x22; },
  value: { type: &#x22;string | Color&#x22;, description: &#x22;Controlled color, when not inside a ColorPicker.&#x22; },
  defaultValue: { type: &#x22;string | Color&#x22; },
  onChange: { type: &#x22;(value: Color) => void&#x22; },
  onChangeEnd: { type: &#x22;(value: Color) => void&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Form name for the channel value.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Overrides the default channel-name label.&#x22; },
  className: { type: &#x22;string | ((state: ColorSliderRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ColorSlider`](https://react-aria.adobe.com/ColorSlider#api). Styled for horizontal sliders only.

### ColorField

<TypeTable
  type="{
  label: { type: &#x22;string&#x22;, description: &#x22;Visible label.&#x22; },
  description: { type: &#x22;string&#x22;, description: &#x22;Helper text under the input.&#x22; },
  placeholder: { type: &#x22;string&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message.&#x22; },
  channel: { type: &#x22;ColorChannel&#x22;, description: &#x22;Edit one channel as a number instead of the hex string.&#x22; },
  colorSpace: { type: '&#x22;rgb&#x22; | &#x22;hsl&#x22; | &#x22;hsb&#x22;', description: &#x22;Color space for channel.&#x22; },
  value: { type: &#x22;string | Color | null&#x22;, description: &#x22;Controlled color.&#x22; },
  defaultValue: { type: &#x22;string | Color | null&#x22; },
  onChange: { type: &#x22;(color: Color | null) => void&#x22;, description: &#x22;Called when typed text is committed (Enter or blur) or the value is stepped.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Name used when submitting a form.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isInvalid: { type: &#x22;boolean&#x22; },
  validate: { type: &#x22;(value: Color | null) => ValidationError | true | null | undefined&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;' },
  isWheelDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Stops the scroll wheel from changing the value.&#x22; },
  className: { type: &#x22;string | ((state: ColorFieldRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ColorField`](https://react-aria.adobe.com/ColorField#api).

### ColorSwatch

<TypeTable
  type="{
  color: { type: &#x22;string | Color&#x22;, description: &#x22;The color to show. Inside a ColorPicker, defaults to the picker's color.&#x22; },
  colorName: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Defaults to a generated description of the color.&#x22; },
  className: { type: &#x22;string | ((state: ColorSwatchRenderProps) => string)&#x22; },
}"
/>

### ColorSwatchPicker

<TypeTable
  type="{
  value: { type: &#x22;string | Color&#x22;, description: &#x22;Controlled selected color.&#x22; },
  defaultValue: { type: &#x22;string | Color&#x22; },
  onChange: { type: &#x22;(value: Color) => void&#x22; },
  layout: { type: '&#x22;grid&#x22; | &#x22;stack&#x22;', default: '&#x22;grid&#x22;', description: &#x22;Keyboard navigation model. The visual layout is always a wrapping row.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;ColorSwatchPickerItem elements.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Required when there's no aria-labelledby.&#x22; },
  className: { type: &#x22;string | ((state) => string)&#x22; },
}"
/>

### ColorSwatchPickerItem

<TypeTable
  type="{
  color: { type: &#x22;string | Color&#x22;, description: &#x22;Required. The preset color.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  className: { type: &#x22;string | ((state: ColorSwatchPickerItemRenderProps) => string)&#x22; },
}"
/>

See React Aria's [`ColorSwatchPicker`](https://react-aria.adobe.com/ColorSwatchPicker#api) and [`ColorSwatch`](https://react-aria.adobe.com/ColorSwatch#api).

### ColorThumb

Accepts React Aria's [`ColorThumb`](https://react-aria.adobe.com/ColorArea#colorthumb) props (`className`, `style`, hover events). `ColorArea` and `ColorSlider` render one for you.

## Related

* [Slider](/docs/components/slider) — the same interaction for plain numbers.
* [Popover](/docs/components/popover) — the overlay the picker opens in.
* [Text Field](/docs/components/text-field) — `ColorField` shares its input styles.

---

# Drop Zone

Source: https://desyne.dev/docs/components/drop-zone

> A drag-and-drop target for files, folders or text, paired with FileTrigger for click-to-browse. Accessible to keyboard and screen-reader users through paste and keyboard drag and drop, with type filtering and a drop-target state for styling.

```tsx title="drop-zone/demo.tsx"
"use client";

import { UploadIcon } from "lucide-react";
import { useState } from "react";
import { isFileDropItem, Text } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { DropZone, FileTrigger } from "@/components/ui/drop-zone";

export default function DropZoneDemo() {
  const [files, setFiles] = useState<string[]>([]);
  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <DropZone
        onDrop={async (e) => {
          const dropped = e.items
            .filter(isFileDropItem)
            .map((item) => item.name);
          setFiles((f) => [...f, ...dropped]);
        }}
      >
        <UploadIcon aria-hidden className="size-6 text-muted-foreground" />
        <Text slot="label" className="font-medium">
          Drop files here
        </Text>
        <span className="text-muted-foreground text-xs">or</span>
        <FileTrigger
          allowsMultiple
          onSelect={(list) =>
            setFiles((f) => [
              ...f,
              ...Array.from(list ?? []).map((file) => file.name),
            ])
          }
        >
          <Button variant="outline" size="sm">
            Browse files
          </Button>
        </FileTrigger>
      </DropZone>
      {files.length > 0 && (
        <ul className="list-inside list-disc text-muted-foreground text-sm">
          {files.map((name, i) => (
            // biome-ignore lint/suspicious/noArrayIndexKey: same file can be added twice
            <li key={`${name}-${i}`}>{name}</li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/drop-zone
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { isFileDropItem, Text } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { DropZone, FileTrigger } from "@/components/ui/drop-zone";
```

```tsx
<DropZone
  onDrop={async (e) => {
    const files = await Promise.all(
      e.items.filter(isFileDropItem).map((item) => item.getFile()),
    );
    upload(files);
  }}
>
  <Text slot="label">Drop files here</Text>
  <FileTrigger allowsMultiple onSelect={(list) => upload(Array.from(list ?? []))}>
    <Button variant="outline" size="sm">Browse files</Button>
  </FileTrigger>
</DropZone>
```

<Callout title="Always offer a file picker">
  Dragging isn't possible on many touch devices and is hard for some users.
  Put a `FileTrigger` button inside (or next to) every drop zone so files can
  also be chosen from the system dialog.
</Callout>

`DropZone` only receives data; it doesn't upload or store anything. `onDrop` gives you `DropItem`s: use `isFileDropItem`, `isDirectoryDropItem` and `isTextDropItem` from `react-aria-components` to narrow them, then `getFile()`, `getEntries()` or `getText(type)` to read them.

### When to use

* Drop Zone — uploading files or accepting dragged data into a specific area of the page.
* `FileTrigger` alone — a plain "Upload" button where dragging adds nothing, such as a single attachment in a dense form.
* [Grid List](/docs/components/grid-list) or [Table](/docs/components/table) with `useDragAndDrop` — reordering or dropping items between positions in a collection.

## Anatomy

```tsx
<DropZone>                 {/* drop target + visually hidden button */}
  <Icon />
  <Text slot="label" />    {/* names the drop zone for screen readers */}
  <FileTrigger>            {/* hidden <input type="file"> */}
    <Button />             {/* opens the system file dialog */}
  </FileTrigger>
</DropZone>
```

| Part                | Renders                              | Notes                                                                                                  |
| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `DropZone`          | `<div>` + visually hidden `<button>` | Dashed box, centered column. The hidden button receives focus, paste and keyboard drops.               |
| `Text slot="label"` | `<span>`                             | From `react-aria-components`. Its text becomes the accessible name of the hidden button.               |
| `FileTrigger`       | hidden `<input type="file">`         | Re-exported from React Aria. Makes its child (any pressable, usually a `Button`) open the file dialog. |

## Examples

### Sizes

`size` sets the minimum height and padding: `sm` for inline attachment areas, `md` (default) for forms, `lg` for a page's primary upload target.

Example `drop-zone/sizes`: source in https://desyne.dev/docs/components/drop-zone.md

### Accepted file types

`getDropOperation` decides whether a drag is accepted while it's still over the zone. Return `"cancel"` for unsupported types and the zone won't highlight or accept the drop. Match it with `acceptedFileTypes` on `FileTrigger`, and still filter in `onDrop`, since some browsers don't reveal file types until the drop.

Example `drop-zone/accepted-types`: source in https://desyne.dev/docs/components/drop-zone.md

### Image previews

Read each `FileDropItem` with `getFile()` and preview it with `URL.createObjectURL`. Revoke the URLs when they're no longer shown.

Example `drop-zone/image-preview`: source in https://desyne.dev/docs/components/drop-zone.md

### Drop-target state

`children` (and `className`) accept a function of the zone's state. Use `isDropTarget` to change the message while something is dragged over it.

Example `drop-zone/render-props`: source in https://desyne.dev/docs/components/drop-zone.md

### Text and paste

Drop zones accept any drag data, not only files. Focus the zone (click it or <kbd>Tab</kbd> to it) and paste with <kbd>Ctrl</kbd> + <kbd>V</kbd> / <kbd>⌘</kbd> + <kbd>V</kbd>: the pasted items arrive through the same `onDrop`, which is how keyboard users can "drop" without dragging.

Example `drop-zone/text`: source in https://desyne.dev/docs/components/drop-zone.md

### Folders

A dropped folder arrives as a `DirectoryDropItem`; iterate `getEntries()` (recursively) to reach its files. On `FileTrigger`, `acceptDirectory` lets users pick a folder instead of files.

Example `drop-zone/directory`: source in https://desyne.dev/docs/components/drop-zone.md

### Disabled

`isDisabled` stops the zone from accepting drops or paste and dims it. Disable the `FileTrigger`'s button too, and say why.

Example `drop-zone/disabled`: source in https://desyne.dev/docs/components/drop-zone.md

### Validation

Check size and count yourself in `onDrop` and `onSelect`, show errors in an `aria-live` region, and disable the zone once the limit is reached. Link the rules to the zone with `aria-describedby`.

Example `drop-zone/validation`: source in https://desyne.dev/docs/components/drop-zone.md

### Form submission

Files held in state aren't part of the form. Append them to the `FormData` in `onSubmit` before sending it.

Example `drop-zone/form`: source in https://desyne.dev/docs/components/drop-zone.md

## Recipes

### Upload list

A compact drop zone with an inline "browse" link, and a list of files with [`ProgressBar`](/docs/components/progress-bar)s and cancel buttons.

Example `drop-zone/recipe-upload-list`: source in https://desyne.dev/docs/components/drop-zone.md

### Avatar upload

A circular drop zone around an [`Avatar`](/docs/components/avatar) that only accepts images, with upload and remove buttons beside it.

Example `drop-zone/recipe-avatar`: source in https://desyne.dev/docs/components/drop-zone.md

### Comment composer

The whole composer is the drop target: a borderless [`Textarea`](/docs/components/textarea), attachment chips and a toolbar. Clicking the textarea still focuses it, because the zone only moves focus to its hidden button when you click a non-focusable area.

Example `drop-zone/recipe-composer`: source in https://desyne.dev/docs/components/drop-zone.md

## Accessibility

* `DropZone` renders a visually hidden `<button>` inside the drop area. Clicking a non-interactive part of the zone focuses it, and <kbd>Tab</kbd> reaches it like any button.
* The hidden button is named by a `Text slot="label"` inside the zone (plus `aria-labelledby`, if passed), or by `aria-label`. Without either, it falls back to a generic "DropZone" label, so always provide one.
* Keyboard and screen-reader users can paste into the focused zone; pasted items are delivered to `onDrop` with the `"copy"` operation.
* During a keyboard or screen-reader drag started from a React Aria draggable (for example a `GridList` using `useDragAndDrop`), drop zones become targets that can be reached with <kbd>Tab</kbd> and dropped on with <kbd>Enter</kbd>.
* `FileTrigger` makes its child open the native file dialog, which is fully accessible. Always include one.
* Announce results (files added, errors) in an `aria-live` region so users know the drop worked.

### Keyboard

| Key                                                          | Action                                                                         |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| <kbd>Tab</kbd>                                               | Moves focus to the drop zone's hidden button, then to the `FileTrigger` button |
| <kbd>Ctrl</kbd> + <kbd>V</kbd> / <kbd>⌘</kbd> + <kbd>V</kbd> | Pastes clipboard contents into the focused zone                                |
| <kbd>Enter</kbd>                                             | During a keyboard drag, drops onto the focused zone                            |
| <kbd>Space</kbd> / <kbd>Enter</kbd> on the button            | Opens the file dialog                                                          |

## Styling

### Data attributes

| Attribute                             | Present when                                                                                   |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `data-drop-target`                    | Something droppable is dragged over the zone (and `getDropOperation` didn't return `"cancel"`) |
| `data-hovered`                        | Hovered with a mouse or pen                                                                    |
| `data-focused` / `data-focus-visible` | The hidden button is focused / focused with the keyboard                                       |
| `data-disabled`                       | `isDisabled` is true                                                                           |

By default the drop-target state switches to a solid brand-colored border on an accent background, and keyboard focus draws a ring.

### Slots

| `data-slot` | Element |
| ----------- | ------- |
| `drop-zone` | Root    |

### Custom layouts

`className` is merged with the defaults, so you can reshape the zone entirely: `min-h-0 p-0` removes the size padding, `items-stretch text-left` undoes the centered column, and `rounded-full` makes a circular target. See the avatar and composer recipes.

### Render props

`className` and `children` accept a function of the zone state:

```tsx
<DropZone className={({ isDropTarget }) => (isDropTarget ? "scale-[1.01]" : "")}>
  {({ isDropTarget }) => (
    <Text slot="label">{isDropTarget ? "Release to upload" : "Drop files here"}</Text>
  )}
</DropZone>
```

## API Reference

### DropZone

<TypeTable
  type="{
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Minimum height and padding.&#x22; },
  onDrop: { type: &#x22;(e: DropEvent) => void&#x22;, description: &#x22;Called with the dropped or pasted items (e.items).&#x22; },
  getDropOperation: { type: &#x22;(types: DragTypes, allowedOperations: DropOperation[]) => DropOperation&#x22;, description: 'Return &#x22;copy&#x22;, &#x22;move&#x22;, &#x22;link&#x22; or &#x22;cancel&#x22;. types.has() accepts a MIME type, an array, or wildcards like &#x22;image/*&#x22;.' },
  onDropEnter: { type: &#x22;(e: DropEnterEvent) => void&#x22;, description: &#x22;Called when a valid drag enters the zone.&#x22; },
  onDropMove: { type: &#x22;(e: DropMoveEvent) => void&#x22;, description: &#x22;Called as a drag moves within the zone.&#x22; },
  onDropActivate: { type: &#x22;(e: DropActivateEvent) => void&#x22;, description: &#x22;Called when a drag hovers over the zone for a while.&#x22; },
  onDropExit: { type: &#x22;(e: DropExitEvent) => void&#x22;, description: &#x22;Called when a drag leaves the zone.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Stops the zone from accepting drops and paste.&#x22; },
  children: { type: &#x22;ReactNode | ((state: DropZoneRenderProps) => ReactNode)&#x22; },
  className: { type: &#x22;string | ((state: DropZoneRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
  onHoverChange: { type: &#x22;(isHovered: boolean) => void&#x22;, description: &#x22;onHoverStart and onHoverEnd are also supported.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name, when there's no Text slot=\&#x22;label\&#x22;.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22; },
  &#x22;aria-describedby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Links rules or hints to the hidden button.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`DropZone`](https://react-aria.adobe.com/DropZone#api).

### FileTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;A pressable element, usually a Button, that opens the file dialog.&#x22; },
  onSelect: { type: &#x22;(files: FileList | null) => void&#x22;, description: &#x22;Called with the chosen files.&#x22; },
  acceptedFileTypes: { type: &#x22;string[]&#x22;, description: 'MIME types or extensions, e.g. [&#x22;image/png&#x22;, &#x22;.pdf&#x22;].' },
  allowsMultiple: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Allows choosing more than one file.&#x22; },
  acceptDirectory: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Choose a folder instead of files.&#x22; },
  defaultCamera: { type: '&#x22;user&#x22; | &#x22;environment&#x22;', description: &#x22;On mobile, opens the front or back camera for capture.&#x22; },
}"
/>

`FileTrigger` is re-exported unchanged from React Aria. See its [props](https://react-aria.adobe.com/FileTrigger#api).

## Related

* [Button](/docs/components/button) — the usual `FileTrigger` child.
* [Progress Bar](/docs/components/progress-bar) — for upload progress.
* [Avatar](/docs/components/avatar) — for profile photo uploads.

---

# Rating

Source: https://desyne.dev/docs/components/rating

> Lets users give a rating with stars (or any icon), and shows existing ratings with half-star precision. Built on React Aria's RadioGroup for arrow-key support and form integration, with three sizes, seven colors, custom icons, labels for each value and field-style label, description and validation.

```tsx title="rating/demo.tsx"
"use client";

import { Rating } from "@/components/ui/rating";

export default function RatingDemo() {
  return (
    <Rating
      label="How was your delivery?"
      description="Your rating is shared with the courier."
      defaultValue={4}
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/rating
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

```tsx
import { Rating } from "@/components/ui/rating";
```

```tsx
<Rating label="How was your delivery?" defaultValue={4} />

<Rating isReadOnly value={4.5} />
```

`value` is a number from `0` (no rating) to `maxValue`. `onChange` receives a number.

### When to use

* Rating: a quick, low-effort score, such as product reviews, satisfaction after a support chat, or rating an article.
* [Radio Group](/docs/components/radio-group): when each value needs a written label the user should read before choosing.
* [Slider](/docs/components/slider): a value on a continuous or fine-grained scale.
* [Meter](/docs/components/meter) with `segments`: a level, not something the user rates.

## Anatomy

```tsx
<Rating>                    {/* role="radiogroup" */}
  {/* Label */}
  {/* icons: one radio per value */}
  {/* value text / value label (optional) */}
  {/* Description, FieldError */}
</Rating>

<Rating isReadOnly />        {/* role="img" with "4.5 out of 5" */}
```

| Part           | Renders                       | Notes                                                                                                   |
| -------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Rating`       | `<div role="radiogroup">`     | React Aria `RadioGroup`, horizontal. Handles arrow keys, `name` for forms, `isRequired` and validation. |
| Item           | `<label>` with a hidden radio | One per value. Its accessible name is `"3 of 5"`, or the matching `valueLabels` entry.                  |
| Icon           | `<span>` × 2                  | A faint base icon with a filled copy on top, clipped to the fill amount.                                |
| Value text     | `<span>`                      | With `showValue`: the number, e.g. `4.5`.                                                               |
| Value label    | `<span aria-hidden>`          | With `valueLabels`: the label for the hovered or selected value.                                        |
| Read-only root | `<div role="img">`            | With `isReadOnly`: not focusable, named "4.5 out of 5".                                                 |

## Examples

### Read-only with half stars

`isReadOnly` renders a static display. Fractional values round to the nearest half, so `4.3` shows four and a half stars. Pair it with the numeric average and the review count.

Example `rating/read-only`: source in https://desyne.dev/docs/components/rating.md

### Sizes

`sm` (16px), `md` (20px, default) and `lg` (28px).

Example `rating/sizes`: source in https://desyne.dev/docs/components/rating.md

### Custom icon and color

Pass any icon to `icon` and a tone to `color` (default `warning`). Use `maxValue` for a shorter scale.

Example `rating/custom-icon`: source in https://desyne.dev/docs/components/rating.md

### Value labels

`valueLabels` names each value. The names are used as each radio's accessible name and shown next to the icons for the hovered or selected value.

Example `rating/value-labels`: source in https://desyne.dev/docs/components/rating.md

### In a form

Ratings work like any React Aria field: `name` submits the value with the form, `isRequired` blocks submission until a value is chosen, and `errorMessage` customizes the message.

Example `rating/form`: source in https://desyne.dev/docs/components/rating.md

## Accessibility

* Interactive ratings are a React Aria `RadioGroup` with one radio per value. Tab moves focus into the group; Left and Right arrows (Up and Down too) change the value, and each change is announced.
* Every radio has a name: `"3 of 5"` by default, or the matching `valueLabels` entry, such as "Helpful".
* Name the group with `label`, `aria-label` or `aria-labelledby`.
* The read-only display is a single `role="img"` element named "4.5 out of 5", prefixed with `label` when you pass one. It isn't focusable.
* Filled and empty icons differ in fill, not only color, so the value reads in high-contrast and grayscale modes.
* Clicking the selected star clears the rating (value `0`); from the keyboard, Backspace or Delete clears it. Turn this off with `allowClear={false}`, for example when a rating is required.

## Styling

### Data attributes

| Attribute                  | On         | Present when |
| -------------------------- | ---------- | ------------ |
| `data-slot="rating"`       | Root       | Always       |
| `data-readonly`            | Root       | `isReadOnly` |
| `data-slot="rating-icon"`  | Each icon  | Always       |
| `data-slot="rating-value"` | Value text | `showValue`  |

The root also gets React Aria's `RadioGroup` attributes (`data-disabled`, `data-invalid`, `data-required`, …) and sets the `group/field` group, like other fields.

### Tone variables

`color` sets `--tone` on the root. Filled icons use `text-(--tone)`; empty icons use `text-(--tone)/20` in light mode and `text-muted-foreground/30` in dark mode.

## API Reference

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label, used as the accessible name.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Help text under the icons.&#x22; },
  errorMessage: { type: &#x22;string | ((validation: ValidationResult) => string)&#x22;, description: &#x22;Shown when the field is invalid.&#x22; },
  value: { type: &#x22;number&#x22;, description: &#x22;Controlled value. 0 means no rating. May be fractional when isReadOnly.&#x22; },
  defaultValue: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: number) => void&#x22;, description: &#x22;Called when the user picks a value.&#x22; },
  maxValue: { type: &#x22;number&#x22;, default: &#x22;5&#x22;, description: &#x22;Number of icons.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, description: &#x22;Renders a static display with half-step precision.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Icon size: 16, 20 or 28px.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', default: '&#x22;warning&#x22;', description: &#x22;Tone of the filled icons.&#x22; },
  icon: { type: &#x22;ReactNode&#x22;, default: &#x22;<StarIcon />&#x22;, description: &#x22;The icon to repeat.&#x22; },
  showValue: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shows the number after the icons.&#x22; },
  valueLabels: { type: &#x22;string[]&#x22;, description: &#x22;Name for each value, from 1 up. Used as accessible names and shown for the hovered or selected value.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Submits the value with a form.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, description: &#x22;Requires a value before the form submits.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables the rating.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes on the root.&#x22; },
}"
/>

Also accepts the props of React Aria's [`RadioGroup`](https://react-aria.adobe.com/RadioGroup#api) except `orientation`, such as `isInvalid`, `validate` and `aria-describedby`.

## Related

* [Radio Group](/docs/components/radio-group): choices with written labels.
* [Slider](/docs/components/slider): a value on a fine-grained scale.
* [Textarea](/docs/components/textarea): pair a rating with a written review.

---

# Input Group

Source: https://desyne.dev/docs/components/input-group

> Attach prefixes, suffixes, icons and buttons to a text input so they read as one field, such as an https:// prefix, a .com suffix, a currency, a copy button or a password toggle. Composes with React Aria's TextField, NumberField and SearchField, and the focus ring wraps the whole group.

```tsx title="input-group/demo.tsx"
"use client";

import { TextField } from "react-aria-components";
import { Description, Label } from "@/components/ui/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/ui/input-group";

export default function InputGroupDemo() {
  return (
    <TextField
      defaultValue="harborpine"
      className="group/field flex w-full max-w-sm flex-col gap-1.5"
    >
      <Label>Website</Label>
      <InputGroup>
        <InputGroupAddon variant="segment">https://</InputGroupAddon>
        <InputGroupInput />
        <InputGroupAddon variant="segment">.com</InputGroupAddon>
      </InputGroup>
      <Description>Shown on your public profile.</Description>
    </TextField>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/input-group
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { TextField } from "react-aria-components";
import { Label } from "@/components/ui/field";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@/components/ui/input-group";
```

```tsx
<TextField className="group/field flex flex-col gap-1.5">
  <Label>Website</Label>
  <InputGroup>
    <InputGroupAddon variant="segment">https://</InputGroupAddon>
    <InputGroupInput />
    <InputGroupAddon variant="segment">.com</InputGroupAddon>
  </InputGroup>
</TextField>
```

`InputGroup` is the same chrome as every other field (`FieldGroup` from `field.tsx`) with the padding moved onto its parts. Put it inside a React Aria field and `InputGroupInput` picks up the value, label, description and validation from the field.

<Callout title="TextField already has prefix and suffix">
  For a single icon or short text inside the field, [Text Field](/docs/components/text-field)'s
  `prefix` and `suffix` props are enough. Reach for Input Group when you need
  flush segments, buttons, several addons, or a `NumberField`.
</Callout>

### When to use

* Input Group: fixed parts of a value (protocol, domain, unit, currency) or actions that act on the input (copy, reveal, clear, submit).
* [Text Field](/docs/components/text-field): a plain input, optionally with one icon or text adornment.
* [Search Field](/docs/components/search-field): search with a built-in clear button.
* [Number Field](/docs/components/number-field): numbers with stepper buttons.

## Anatomy

```tsx
<TextField>                         {/* or NumberField, SearchField */}
  <Label />
  <InputGroup>                      {/* role="group", draws the border and focus ring */}
    <InputGroupAddon />             {/* inline text or icon, or a flush segment */}
    <InputGroupInput />             {/* the <input> */}
    <InputGroupButton />            {/* ghost button inside, or a flush segment */}
  </InputGroup>
  <Description />
  <FieldError />
</TextField>
```

| Part               | Renders                             | Notes                                                                                                                                                                       |
| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InputGroup`       | React Aria `Group` (`role="group"`) | Field chrome with `variant` (outline, filled, underlined) and `size`. Shows the focus ring when anything inside has focus, and the invalid style when the field is invalid. |
| `InputGroupInput`  | React Aria `Input`                  | Bare input that fills the space. Pads itself only at the group's edges.                                                                                                     |
| `InputGroupAddon`  | `<span>`                            | `inline`: muted text or icon inside the field. `segment`: a flush, tinted box divided by a border.                                                                          |
| `InputGroupButton` | React Aria `Button`                 | `ghost` (default): a small icon button inside the field. `segment`: a flush, full-height button divided by a border.                                                        |

## Examples

### Icons and inline text

Inline addons sit inside the border, before or after the input: a search icon, a [`Kbd`](/docs/components/kbd) shortcut, a character count.

Example `input-group/icons`: source in https://desyne.dev/docs/components/input-group.md

### Buttons

`InputGroupButton` defaults to a 24px ghost icon button. Give icon-only buttons an `aria-label`. For a password toggle, switch the field's `type`.

Example `input-group/buttons`: source in https://desyne.dev/docs/components/input-group.md

### Segment button

`variant="segment"` turns the button into a flush, full-height part of the field, for actions like Subscribe or Apply. `type="submit"` submits the surrounding form.

Example `input-group/segment-button`: source in https://desyne.dev/docs/components/input-group.md

### Currency and units

The same parts work inside a React Aria `NumberField`: the input is formatted and parsed in the user's locale, and Up and Down arrows change the value.

Example `input-group/currency`: source in https://desyne.dev/docs/components/input-group.md

### Variants and sizes

`variant` and `size` work as on every other field. Underlined groups drop the side padding so content lines up with the underline.

Example `input-group/variants`: source in https://desyne.dev/docs/components/input-group.md

## Accessibility

* The input gets its name from the surrounding field's `Label` (or `aria-label` on the field), and its description and error message through React Aria.
* `InputGroup` is a React Aria `Group` with `role="group"`. The focus ring is drawn on the group when the input or a button inside it has focus, so it always wraps the full field.
* Addons are plain text. A screen reader user won't hear "https\://" when focusing the input; if the prefix matters, mention it in the label or description ("Website, without https\://").
* Buttons are separate tab stops after (or before) the input. Icon-only buttons need an `aria-label`, and buttons that change state (copy, reveal) should update it ("Copied", "Hide password").

## Styling

### Data attributes

| Attribute                        | On                 | Values                                                                                         |
| -------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `data-slot="input-group"`        | `InputGroup`       | Always, plus React Aria's `data-focus-within`, `data-hovered`, `data-invalid`, `data-disabled` |
| `data-slot="input-group-input"`  | `InputGroupInput`  | Always                                                                                         |
| `data-slot="input-group-addon"`  | `InputGroupAddon`  | Always                                                                                         |
| `data-slot="input-group-button"` | `InputGroupButton` | Always                                                                                         |
| `data-variant`                   | Addon, button      | `inline` · `segment` / `ghost` · `segment`                                                     |

### Padding

Parts read `--ig-px` for their edge padding: 8, 10 and 12px for `sm`, `md` and `lg`, and 0 for underlined groups. Override it on the group: `className="[--ig-px:--spacing(4)]"`.

## API Reference

### InputGroup

<TypeTable
  type="{
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;', description: &#x22;Field surface, as on every other field.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Height: 28, 32 or 40px.&#x22; },
  className: { type: &#x22;string | ((state: GroupRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Group`](https://react-aria.adobe.com/Group#api).

### InputGroupAddon

<TypeTable
  type="{
  variant: { type: '&#x22;inline&#x22; | &#x22;segment&#x22;', default: '&#x22;inline&#x22;', description: &#x22;Inside the field, or a flush tinted segment with a divider.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<span>`.

### InputGroupButton

<TypeTable
  type="{
  variant: { type: '&#x22;ghost&#x22; | &#x22;segment&#x22;', default: '&#x22;ghost&#x22;', description: &#x22;A small button inside the field, or a flush full-height segment.&#x22; },
  size: { type: &#x22;ButtonProps['size']&#x22;, default: '&#x22;icon-xs&#x22;', description: &#x22;Button size. Segment buttons use sm unless set.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', default: '&#x22;neutral&#x22;', description: &#x22;Tone of the button.&#x22; },
  className: { type: &#x22;string | ((state: ButtonRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Button`](https://react-aria.adobe.com/Button#api), such as `onPress` and `type`.

### InputGroupInput

Accepts every prop of React Aria's [`Input`](https://react-aria.adobe.com/TextField#input), such as `placeholder`.

## Related

* [Text Field](/docs/components/text-field): single icon or text adornments.
* [Number Field](/docs/components/number-field): numeric input with steppers.

---

# Calendar

Source: https://desyne.dev/docs/components/calendar

> An inline month grid for picking a single date, several dates or a date range. Supports min/max bounds, unavailable dates, multiple visible months, any locale and calendar system, and full keyboard navigation.

```tsx title="calendar/demo.tsx"
"use client";

import { getLocalTimeZone, today } from "@internationalized/date";
import { Calendar } from "@/components/ui/calendar";

export default function CalendarDemo() {
  return (
    <Calendar
      aria-label="Appointment date"
      defaultValue={today(getLocalTimeZone())}
      className="rounded-lg border bg-card shadow-xs"
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/calendar
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { Calendar, RangeCalendar } from "@/components/ui/calendar";
import { getLocalTimeZone, today } from "@internationalized/date";
```

```tsx
<Calendar aria-label="Due date" defaultValue={today(getLocalTimeZone())} />
```

<Callout title="Dates are @internationalized/date objects">
  Values are `CalendarDate` (or `CalendarDateTime` / `ZonedDateTime`) objects
  from [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/),
  not JavaScript `Date`s. Create them with `today(getLocalTimeZone())` or
  `parseDate("2027-03-15")`, compare them with `a.compare(b)`, and convert with
  `date.toDate(timeZone)` when you need a `Date`. The calendar follows the
  user's locale, calendar system and first day of the week automatically.
</Callout>

### When to use

* Calendar — an always-visible grid, for scheduling screens, booking flows and sidebars where the month context matters.
* [Date Picker](/docs/components/date-picker) — a compact field that opens this calendar in a popover. The right default inside forms.
* [Date Field](/docs/components/date-field) — typed entry only, for dates users already know (birthdays, document dates) where a grid adds nothing.
* `RangeCalendar` — a start and end date. Use [Date Range Picker](/docs/components/date-picker#range) inside forms.

## Anatomy

```tsx
<Calendar>                 {/* or <RangeCalendar> */}
  <header>
    <Button slot="previous" />
    <Heading />            {/* "March 2027"; visually hidden with dropdowns */}
    {/* captionLayout="dropdown": month <Select> + year <Select> */}
    <Button slot="next" />
  </header>
  <CalendarGrid>           {/* one per visible month */}
    <CalendarGridHeader>   {/* weekday names */}
    <CalendarGridBody>
      <CalendarCell />     {/* one per day */}
    </CalendarGridBody>
  </CalendarGrid>
  <Text slot="errorMessage" />   {/* when errorMessage is set */}
</Calendar>
```

| Part            | Renders                                 | Notes                                                                                                                                               |
| --------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Calendar`      | `<div>`                                 | Single date, or several dates with `selectionMode="multiple"`. `data-slot="calendar"`.                                                              |
| `RangeCalendar` | `<div>`                                 | A contiguous start/end range. `data-slot="range-calendar"`.                                                                                         |
| Previous / next | `<button>`                              | Ghost icon [`Button`](/docs/components/button)s. Disabled automatically at `minValue` / `maxValue`.                                                 |
| Heading         | `<h2 aria-hidden>`                      | The visible month (or range of months), formatted for the locale. Screen readers get the month from the grid label instead.                         |
| Caption selects | `Select` › `<button>` + listbox popover | With `captionLayout` set to a dropdown layout. Labelled with the localized words for month and year. `data-slot="calendar-caption"` on the wrapper. |
| Grid            | `<table role="grid">`                   | Rendered once per month in `visibleDuration`. Weekdays use the `short` style.                                                                       |
| Cell            | `<td>` › `<div role="button">`          | Each date. All states are exposed as data attributes.                                                                                               |
| Error message   | `<span slot="errorMessage">`            | Shown below the grid whenever `errorMessage` is set.                                                                                                |

The header, grid and cells are built in, so the only thing you pass is props. For a custom layout, compose React Aria's [`Calendar`](https://react-aria.adobe.com/Calendar) parts directly and reuse the cell styles from the source.

## Examples

### Controlled

Use `value` and `onChange` to own the selected date. Format it for display with `DateFormatter` and the current locale from `useLocale()`.

Example `calendar/controlled`: source in https://desyne.dev/docs/components/calendar.md

### Range

`RangeCalendar` selects a start and end date. Click (or press <kbd>Enter</kbd>) once to set the start, and again to set the end. The value is `{ start, end }`.

Example `calendar/range`: source in https://desyne.dev/docs/components/calendar.md

### Min and max dates

`minValue` and `maxValue` disable dates outside the bounds. Disabled dates can't be focused, and the previous and next buttons disable themselves at the edges.

Example `calendar/min-max`: source in https://desyne.dev/docs/components/calendar.md

### Month and year dropdowns

`captionLayout="dropdown"` replaces the heading with a month select and a year select, so users can jump years at a time. That's the right choice for dates far from today, such as a birth date. The arrows still page one month at a time.

The year list runs from `fromYear` to `toYear`. Without them it uses the years of `minValue` and `maxValue`, then falls back to 100 years ago through 10 years ahead. Months outside `minValue` / `maxValue` are disabled in the month list.

Example `calendar/caption-dropdown`: source in https://desyne.dev/docs/components/calendar.md

### Caption layouts

`captionLayout` takes four values: `label` (the default heading), `dropdown` (both selects), `dropdown-months` (a month select and the year as text) and `dropdown-years` (the month as text and a year select). Month names and years follow the locale and calendar system.

Example `calendar/caption-layouts`: source in https://desyne.dev/docs/components/calendar.md

### Dropdowns in a range calendar

`RangeCalendar` takes the same props. With several visible months, the selects follow the focused month, and picking a month scrolls it into view. Here the window is limited to 11 months, so `dropdown-months` is enough.

Example `calendar/caption-range`: source in https://desyne.dev/docs/components/calendar.md

### Unavailable dates

`isDateUnavailable` marks individual dates (holidays, booked days, weekends) as unavailable. Unlike disabled dates, they stay focusable so keyboard and screen reader users can still reach them, and they're struck through.

Example `calendar/unavailable`: source in https://desyne.dev/docs/components/calendar.md

### Ranges across unavailable dates

By default a range can't include an unavailable date. Set `allowsNonContiguousRanges` to let the range span them, for example a leave request across a weekend. For `RangeCalendar`, `isDateUnavailable` also receives the anchor date (the first date clicked), so you can make availability depend on the start date.

Example `calendar/range-unavailable`: source in https://desyne.dev/docs/components/calendar.md

### Multiple months

`visibleDuration={{ months: 2 }}` shows consecutive months side by side (stacked on narrow screens). `pageBehavior="single"` pages one month at a time instead of a whole visible page.

Example `calendar/multiple-months`: source in https://desyne.dev/docs/components/calendar.md

### Multiple dates

`selectionMode="multiple"` lets users toggle any number of separate dates. The value is a read-only array.

Example `calendar/multiple-selection`: source in https://desyne.dev/docs/components/calendar.md

### First day of the week

The first weekday comes from the locale (Sunday in `en-US`, Monday in most of Europe). Override it with `firstDayOfWeek`.

Example `calendar/first-day`: source in https://desyne.dev/docs/components/calendar.md

### Locales and calendar systems

Wrap the calendar in `I18nProvider` to set a locale. Month and weekday names, digits, text direction and the calendar system all follow it. Add a `-u-ca-` extension for non-Gregorian calendars (`ja-JP-u-ca-japanese`, `th-TH-u-ca-buddhist`). The value you receive is still a `CalendarDate` in that calendar; convert with `toCalendar(date, new GregorianCalendar())` before storing it.

Example `calendar/locales`: source in https://desyne.dev/docs/components/calendar.md

### Controlling the visible month

`focusedValue` and `onFocusChange` control which date has focus, and therefore which month is visible. Use them for "Today" or "Jump to" buttons. `defaultFocusedValue` sets only the initial month.

Example `calendar/focused-value`: source in https://desyne.dev/docs/components/calendar.md

### Validation

Set `isInvalid` from your own logic and pass `errorMessage` to explain it. The selected date turns red, and the message is shown below the grid and linked to it for screen readers.

Example `calendar/validation`: source in https://desyne.dev/docs/components/calendar.md

### Disabled and read-only

`isDisabled` makes the whole calendar non-interactive. `isReadOnly` keeps it focusable and navigable, but the value can't change.

Example `calendar/disabled`: source in https://desyne.dev/docs/components/calendar.md

## Recipes

### Booking with a minimum stay

A `RangeCalendar` with already-booked nights marked unavailable, a minimum-stay rule shown through `isInvalid` and `errorMessage`, and a live price summary.

Example `calendar/recipe-booking`: source in https://desyne.dev/docs/components/calendar.md

### Appointment scheduler

Pick a weekday within the next six weeks, then a time slot from a [`ToggleButtonGroup`](/docs/components/toggle-button-group). Changing the date resets the slot.

Example `calendar/recipe-appointment`: source in https://desyne.dev/docs/components/calendar.md

### Range presets

Preset buttons set both `value` and `focusedValue`, so the calendar jumps to the chosen period. `maxValue` blocks future dates in a reporting context.

Example `calendar/recipe-presets`: source in https://desyne.dev/docs/components/calendar.md

## Accessibility

* The calendar is a `role="application"` group containing one `role="grid"` table per visible month, labelled by the visible month range.
* Give the calendar an accessible name with `aria-label` or `aria-labelledby`. It's combined with the visible month when announced.
* When the visible month changes, the new month is announced through a live region. Selecting a date or completing a range announces the selection.
* Each cell's label includes the full date (weekday, day, month and year), plus "Today" and "selected" where relevant.
* Unavailable dates stay focusable and are announced as unavailable. Disabled dates (outside `minValue` / `maxValue`) are skipped.
* Today is marked with a dot, not just color, and unavailable dates use a strikethrough.
* With `errorMessage`, the message is linked to the calendar with `aria-describedby`.

### Keyboard

| Key                                                                         | Action                                                              |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| <kbd>Tab</kbd>                                                              | Moves between the previous button, next button and the grid         |
| <kbd>←</kbd> / <kbd>→</kbd>                                                 | Previous / next day (reversed in RTL locales)                       |
| <kbd>↑</kbd> / <kbd>↓</kbd>                                                 | Same day in the previous / next week                                |
| <kbd>Home</kbd> / <kbd>End</kbd>                                            | First / last day of the month                                       |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                                   | Previous / next month                                               |
| <kbd>Shift</kbd>+<kbd>Page Up</kbd> / <kbd>Shift</kbd>+<kbd>Page Down</kbd> | Previous / next year                                                |
| <kbd>Enter</kbd> / <kbd>Space</kbd>                                         | Selects the focused date (in a range: sets the start, then the end) |
| <kbd>Esc</kbd>                                                              | Cancels a range selection in progress                               |

With a dropdown `captionLayout`, the month and year selects sit between the previous and next buttons in the tab order. <kbd>Enter</kbd>, <kbd>Space</kbd> or <kbd>↓</kbd> opens a select, typing jumps to a matching month or year, and the grid moves to the chosen month.

## Styling

### Data attributes

On the `Calendar` / `RangeCalendar` root:

| Attribute       | Present when         |
| --------------- | -------------------- |
| `data-disabled` | `isDisabled` is true |
| `data-invalid`  | `isInvalid` is true  |

On each date cell:

| Attribute                                     | Present when                                                 |
| --------------------------------------------- | ------------------------------------------------------------ |
| `data-selected`                               | The date is selected (or inside the selected range)          |
| `data-selection-start` / `data-selection-end` | First / last date of a range                                 |
| `data-today`                                  | The date is today                                            |
| `data-focused` / `data-focus-visible`         | The cell has focus / keyboard focus                          |
| `data-hovered` / `data-pressed`               | Hovered with a mouse / being pressed                         |
| `data-disabled`                               | Outside `minValue` / `maxValue`, or the calendar is disabled |
| `data-unavailable`                            | `isDateUnavailable` returned true                            |
| `data-outside-month`                          | The date belongs to the previous or next month               |
| `data-outside-visible-range`                  | The date is outside the visible range                        |
| `data-invalid`                                | The date is part of an invalid selection                     |

### Slots

| `data-slot`        | Element                                 |
| ------------------ | --------------------------------------- |
| `calendar`         | `Calendar` root                         |
| `range-calendar`   | `RangeCalendar` root                    |
| `calendar-caption` | Wrapper around the month / year selects |

### Customizing

* `className` styles the root (default `w-fit p-3`). It accepts a function of `{ isDisabled, isInvalid, state }`.
* Frame the calendar with classes like `rounded-lg border bg-card`, as in the examples, or leave it bare inside a card or popover.
* Selected dates use the `brand` color; range middles use `accent`. Change the theme tokens to restyle every calendar at once.
* Cells are `size-8`. For a different density, copy the component and adjust `cellBase`.

## API Reference

### Calendar

<TypeTable
  type="{
  value: { type: &#x22;DateValue | null&#x22;, description: &#x22;Controlled value. An array when selectionMode is multiple.&#x22; },
  defaultValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: DateValue) => void&#x22;, description: &#x22;Called when the user selects a date. Receives an array when selectionMode is multiple.&#x22; },
  selectionMode: { type: '&#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;single&#x22;', description: &#x22;Select one date, or toggle any number of dates.&#x22; },
  minValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Earliest selectable date. Earlier dates are disabled.&#x22; },
  maxValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Latest selectable date. Later dates are disabled.&#x22; },
  isDateUnavailable: { type: &#x22;(date: DateValue) => boolean&#x22;, description: &#x22;Marks dates as unavailable. They stay focusable but can't be selected.&#x22; },
  visibleDuration: { type: &#x22;DateDuration&#x22;, default: &#x22;{ months: 1 }&#x22;, description: &#x22;How much is visible at once. One grid is rendered per month.&#x22; },
  pageBehavior: { type: '&#x22;visible&#x22; | &#x22;single&#x22;', default: '&#x22;visible&#x22;', description: &#x22;Page by the whole visible duration, or by one unit of it.&#x22; },
  firstDayOfWeek: { type: '&#x22;sun&#x22; | &#x22;mon&#x22; | &#x22;tue&#x22; | &#x22;wed&#x22; | &#x22;thu&#x22; | &#x22;fri&#x22; | &#x22;sat&#x22;', description: &#x22;Overrides the locale's first day of the week.&#x22; },
  focusedValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Controlled focused date (controls the visible month).&#x22; },
  defaultFocusedValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Initial focused date.&#x22; },
  onFocusChange: { type: &#x22;(date: CalendarDate) => void&#x22;, description: &#x22;Called when the focused date changes.&#x22; },
  selectionAlignment: { type: '&#x22;start&#x22; | &#x22;center&#x22; | &#x22;end&#x22;', default: '&#x22;center&#x22;', description: &#x22;Where the selection sits among visible months on first render.&#x22; },
  weeksInMonth: { type: &#x22;number&#x22;, description: &#x22;Overrides the number of week rows set by the locale.&#x22; },
  captionLayout: { type: '&#x22;label&#x22; | &#x22;dropdown&#x22; | &#x22;dropdown-months&#x22; | &#x22;dropdown-years&#x22;', default: '&#x22;label&#x22;', description: &#x22;How the month and year are shown in the header: a heading, or month and/or year selects.&#x22; },
  fromYear: { type: &#x22;number&#x22;, description: &#x22;First year in the year select. Defaults to minValue's year, or 100 years ago.&#x22; },
  toYear: { type: &#x22;number&#x22;, description: &#x22;Last year in the year select. Defaults to maxValue's year, or 10 years ahead.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Marks the selection as invalid.&#x22; },
  errorMessage: { type: &#x22;string&#x22;, description: &#x22;Text shown below the grid. Pair it with isInvalid.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the whole calendar.&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Keeps the calendar navigable but prevents changes.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Focuses the calendar on mount.&#x22; },
  createCalendar: { type: &#x22;(identifier: CalendarIdentifier) => Calendar&#x22;, description: &#x22;Limits which calendar systems are bundled. Defaults to all.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required when there's no aria-labelledby.&#x22; },
  className: { type: &#x22;string | ((state: CalendarRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Calendar`](https://react-aria.adobe.com/Calendar#api), except `children`.

### RangeCalendar

Accepts every `Calendar` prop above except `selectionMode`, with these differences:

<TypeTable
  type="{
  value: { type: &#x22;RangeValue<DateValue> | null&#x22;, description: &#x22;Controlled range: { start, end }.&#x22; },
  defaultValue: { type: &#x22;RangeValue<DateValue> | null&#x22;, description: &#x22;Uncontrolled initial range.&#x22; },
  onChange: { type: &#x22;(range: RangeValue<DateValue>) => void&#x22;, description: &#x22;Called when a range is completed.&#x22; },
  isDateUnavailable: { type: &#x22;(date: DateValue, anchorDate: CalendarDate | null) => boolean&#x22;, description: &#x22;Also receives the first date the user picked, if any.&#x22; },
  allowsNonContiguousRanges: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Allows a range to include unavailable dates.&#x22; },
  commitBehavior: { type: '&#x22;select&#x22; | &#x22;clear&#x22; | &#x22;reset&#x22;', default: '&#x22;select&#x22;', description: &#x22;What happens when a pointer is released outside, or focus leaves, mid-selection.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`RangeCalendar`](https://react-aria.adobe.com/RangeCalendar#api), except `children`.

## Related

* [Date Picker](/docs/components/date-picker) — this calendar in a popover, attached to a date field.
* [Date Field](/docs/components/date-field) — typed, segmented date and time entry.
* [Toggle Button Group](/docs/components/toggle-button-group) — for time slots next to a calendar.
* [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) — creating, comparing and converting date values.

---

# Date Field

Source: https://desyne.dev/docs/components/date-field

> Segmented date and time inputs that users type into or step with the arrow keys. DateField and TimeField format every segment for the user's locale, support time zones and any granularity down to seconds, and validate against min/max, required and custom rules.

```tsx title="date-field/demo.tsx"
"use client";

import { DateField } from "@/components/ui/date-field";

export default function DateFieldDemo() {
  return (
    <DateField
      label="Invoice date"
      description="As printed on the invoice."
      className="w-full max-w-56"
    />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/date-field
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { DateField, TimeField } from "@/components/ui/date-field";
import { parseDate, Time } from "@internationalized/date";
```

```tsx
<DateField label="Invoice date" defaultValue={parseDate("2027-01-15")} />
<TimeField label="Standup" defaultValue={new Time(9, 30)} />
```

<Callout title="Values are @internationalized/date objects">
  `DateField` takes a `CalendarDate`, `CalendarDateTime` or `ZonedDateTime`, and
  `TimeField` takes a `Time` (or either date-time type). Create them with
  `parseDate`, `parseDateTime`, `parseZonedDateTime`, `today()` or `new Time()`
  from [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/).
  `onChange` gives you the same type back, so time zones and calendar systems
  are never lost in a round trip.
</Callout>

### When to use

* Date Field — dates users already know and type faster than they click: birthdays, document and expiry dates.
* Time Field — a time of day without a date: opening hours, reminders, recurring schedules.
* [Date Picker](/docs/components/date-picker) — the same field plus a calendar popover, for dates users need to see in context ("next Tuesday").
* [Calendar](/docs/components/calendar) — an always-visible grid, when there's room and browsing the month matters.

Prefer these over `<input type="date">`: the segments are consistent across browsers, follow the user's locale and calendar, and are fully accessible.

## Anatomy

```tsx
<DateField>              {/* or <TimeField> */}
  <Label />              {/* from label */}
  <DateInput>            {/* the field chrome */}
    <DateSegment />      {/* month */}
    <DateSegment />      {/* literal "/" */}
    <DateSegment />      {/* day, year, hour, … */}
  </DateInput>
  <Description />        {/* from description */}
  <FieldError />         {/* from errorMessage / validation */}
  <input type="hidden" /> {/* for form submission */}
</DateField>
```

| Part        | Renders                     | Notes                                                                                          |
| ----------- | --------------------------- | ---------------------------------------------------------------------------------------------- |
| `DateField` | `<div>`                     | Root. Labels, validation and the hidden form input. `data-slot="date-field"`.                  |
| `TimeField` | `<div>`                     | Same structure for times. `data-slot="time-field"`.                                            |
| `DateInput` | `<div role="group">`        | Draws the field chrome with the shared `variant` and `size` styles. `data-slot="date-input"`.  |
| Segment     | `<span role="spinbutton">`  | One per editable part. Literals (`/`, `:`, spaces) are plain spans with `data-type="literal"`. |
| Label       | `<span>`                    | Rendered when `label` is set. Adds a red `*` when `isRequired`.                                |
| Description | `<span slot="description">` | Rendered when `description` is set.                                                            |
| FieldError  | `<span>`                    | Shown when the field is invalid. Uses `errorMessage`, or the browser's message.                |

`DateInput` is exported on its own, so you can build a custom layout inside React Aria's `DateField` or `TimeField` and still get the library's field styles.

## Examples

### Controlled

`value` and `onChange` own the value. Set it to `null` to clear every segment. `date.toString()` gives an ISO 8601 string for storage or APIs.

Example `date-field/controlled`: source in https://desyne.dev/docs/components/date-field.md

### Granularity

`granularity` sets the smallest segment shown: `day` (default for dates), `hour`, `minute` or `second`. Time granularities need a value that has a time, such as `CalendarDateTime` or `ZonedDateTime`; without a value, the field picks the right type for you.

Example `date-field/granularity`: source in https://desyne.dev/docs/components/date-field.md

### Time field

`TimeField` shows hours, minutes and the day period. Its value is a `Time`.

Example `date-field/time-field`: source in https://desyne.dev/docs/components/date-field.md

### Time options

`granularity` works on `TimeField` too (`hour`, `minute` by default, or `second`). `hourCycle={24}` forces a 24-hour clock regardless of locale.

Example `date-field/time-options`: source in https://desyne.dev/docs/components/date-field.md

### Time zones

With a `ZonedDateTime` value the field shows the time zone abbreviation and handles daylight saving transitions correctly. Convert between zones with `toTimeZone`. `hideTimeZone` hides the abbreviation when the zone is shown elsewhere.

Example `date-field/time-zones`: source in https://desyne.dev/docs/components/date-field.md

### Placeholder value

When the field is empty, arrow keys start from today (or midnight). `placeholderValue` changes that starting point, which saves a lot of key presses for birthdays, and also sets the value type when there's no `value`.

Example `date-field/placeholder-value`: source in https://desyne.dev/docs/components/date-field.md

### Min and max

`minValue` and `maxValue` mark out-of-range values as invalid and show a localized error. With the default `validationBehavior="native"` the error appears after the user changes the value or submits the form; this example uses `"aria"` so it shows immediately.

Example `date-field/min-max`: source in https://desyne.dev/docs/components/date-field.md

### Validation

`isRequired`, `minValue` / `maxValue` and a custom `validate` function run together. Pass a function to `errorMessage` to tailor the text per failure using `validationDetails`. With `validationBehavior="aria"` on the form, errors appear as the user types instead of on submit.

Example `date-field/validation`: source in https://desyne.dev/docs/components/date-field.md

### Form submission

Set `name` and the value is submitted as an ISO 8601 string (`2027-03-15`, `09:30:00`), ready to parse on the server with `parseDate` or `parseTime`.

Example `date-field/form`: source in https://desyne.dev/docs/components/date-field.md

### Variants

The same `outline`, `filled` and `underlined` variants as every other field.

Example `date-field/variants`: source in https://desyne.dev/docs/components/date-field.md

### Sizes

Example `date-field/sizes`: source in https://desyne.dev/docs/components/date-field.md

### Disabled and read-only

`isDisabled` removes the field from the tab order. `isReadOnly` keeps it focusable and readable by screen readers, but the value can't change.

Example `date-field/disabled`: source in https://desyne.dev/docs/components/date-field.md

### Locales and calendars

Segment order, separators, the day period and digits follow the locale. Wrap fields in `I18nProvider` to set one explicitly, and add a `-u-ca-` extension (`fa-IR-u-ca-persian`) for other calendar systems.

Example `date-field/locales`: source in https://desyne.dev/docs/components/date-field.md

### Leading zeros

Whether months, days and hours are zero-padded comes from the locale. `shouldForceLeadingZeros` always pads them.

Example `date-field/leading-zeros`: source in https://desyne.dev/docs/components/date-field.md

## Recipes

### Date of birth

`placeholderValue` starts the year segment in 1990, `autoComplete="bday"` enables autofill, and `validate` enforces a minimum age. The computed age is shown in the description.

Example `date-field/recipe-date-of-birth`: source in https://desyne.dev/docs/components/date-field.md

### Business hours

One row per day with a [`Switch`](/docs/components/switch) and a pair of small `TimeField`s. Each time field is labelled with `aria-label`, and the closing time is flagged with `isInvalid` when it isn't after the opening time.

Example `date-field/recipe-business-hours`: source in https://desyne.dev/docs/components/date-field.md

### Event in another time zone

A date, start and end `TimeField`s and a time zone [`Select`](/docs/components/select). `toCalendarDateTime` and `toZoned` combine them into one instant, shown back in the viewer's own time zone.

Example `date-field/recipe-event`: source in https://desyne.dev/docs/components/date-field.md

## Accessibility

* The input is a `role="group"` labelled by `label` (or `aria-label`), and each segment is a `role="spinbutton"` announced with its name ("month", "hour") and current value.
* Segments are ordered and labelled for the locale, including right-to-left layouts.
* Typing digits fills a segment and moves to the next one automatically. Typing a letter in the day period segment switches AM/PM.
* `description` and the error message are linked with `aria-describedby`. Invalid fields set `aria-invalid`.
* When `name` is set, a hidden input carries the value for native form submission and validation.
* Use `autoComplete` (for example `bday`) so browsers can autofill.

### Keyboard

| Key                                       | Action                                                     |
| ----------------------------------------- | ---------------------------------------------------------- |
| <kbd>Tab</kbd>                            | Moves to the next segment, then out of the field           |
| <kbd>←</kbd> / <kbd>→</kbd>               | Moves between segments                                     |
| <kbd>↑</kbd> / <kbd>↓</kbd>               | Increments / decrements the focused segment (wraps around) |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | Increments / decrements by a larger step                   |
| <kbd>Home</kbd> / <kbd>End</kbd>          | Sets the segment to its minimum / maximum                  |
| <kbd>0</kbd>–<kbd>9</kbd>                 | Types a value; moves on when the segment is complete       |
| <kbd>Backspace</kbd> / <kbd>Delete</kbd>  | Clears the last digit, then the segment                    |

## Styling

### Data attributes

On the `DateField` / `TimeField` root (use `group-data-*/field:` for children):

| Attribute       | Present when                            |
| --------------- | --------------------------------------- |
| `data-invalid`  | Validation failed or `isInvalid` is set |
| `data-disabled` | `isDisabled` is true                    |
| `data-readonly` | `isReadOnly` is true                    |
| `data-required` | `isRequired` is true                    |

On `DateInput`:

| Attribute                                  | Present when                         |
| ------------------------------------------ | ------------------------------------ |
| `data-focus-within` / `data-focus-visible` | A segment has focus / keyboard focus |
| `data-hovered`                             | Hovered with a mouse                 |
| `data-invalid` / `data-disabled`           | Mirrors the field                    |

On each segment:

| Attribute                             | Present when                                                                                                |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `data-type`                           | Always: `month`, `day`, `year`, `hour`, `minute`, `second`, `dayPeriod`, `era`, `timeZoneName` or `literal` |
| `data-placeholder`                    | The segment is empty and showing its placeholder                                                            |
| `data-focused` / `data-focus-visible` | The segment has focus / keyboard focus                                                                      |
| `data-hovered`                        | Hovered with a mouse                                                                                        |
| `data-readonly`                       | Not editable (literals, time zone, read-only fields)                                                        |
| `data-invalid` / `data-disabled`      | Mirrors the field                                                                                           |

### Slots

| `data-slot`                           | Element             |
| ------------------------------------- | ------------------- |
| `date-field` / `time-field`           | Root                |
| `date-input`                          | The segmented input |
| `label`, `description`, `field-error` | Field text          |

### Style helpers

`dateSegmentStyles` is the class string applied to every segment. `DatePicker` reuses it, and you can too when composing your own inputs:

```tsx
import { dateSegmentStyles } from "@/components/ui/date-field";

<DateSegment segment={segment} className={dateSegmentStyles} />
```

The chrome comes from the shared `fieldVariants` in `field.tsx`, so `variant` and `size` match [Text Field](/docs/components/text-field) and [Select](/docs/components/select). `className` on the root accepts a function of the render props (`isInvalid`, `isDisabled`, `isReadOnly`, `isRequired`, `state`).

## API Reference

### DateField

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text under the input.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  value: { type: &#x22;DateValue | null&#x22;, description: &#x22;Controlled value.&#x22; },
  defaultValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: DateValue | null) => void&#x22;, description: &#x22;Called when a complete value is entered or cleared.&#x22; },
  granularity: { type: '&#x22;day&#x22; | &#x22;hour&#x22; | &#x22;minute&#x22; | &#x22;second&#x22;', default: '&#x22;day&#x22;', description: &#x22;Smallest unit shown.&#x22; },
  placeholderValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Where arrow keys start when empty. Defaults to today at midnight.&#x22; },
  minValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Earliest valid value.&#x22; },
  maxValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Latest valid value.&#x22; },
  isDateUnavailable: { type: &#x22;(date: DateValue) => boolean&#x22;, description: &#x22;Marks specific dates invalid.&#x22; },
  hourCycle: { type: &#x22;12 | 24&#x22;, description: &#x22;Overrides the locale's hour cycle.&#x22; },
  hideTimeZone: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Hides the time zone segment of zoned values.&#x22; },
  shouldForceLeadingZeros: { type: &#x22;boolean&#x22;, description: &#x22;Always zero-pads month, day and hour.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires a value before the form can submit.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state (e.g. for server errors).&#x22; },
  validate: { type: &#x22;(value: DateValue) => string | string[] | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, description: &#x22;Focuses the first segment on mount.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Submits the value as an ISO 8601 string with forms.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  autoComplete: { type: &#x22;string&#x22;, description: &#x22;Autofill hint, e.g. bday.&#x22; },
  onFocus: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onBlur: { type: &#x22;(e: FocusEvent) => void&#x22; },
  onFocusChange: { type: &#x22;(isFocused: boolean) => void&#x22; },
  className: { type: &#x22;string | ((state: DateFieldRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`DateField`](https://react-aria.adobe.com/DateField#api).

### TimeField

Accepts the same field props (`label`, `description`, `errorMessage`, `variant`, `size`, validation, form and focus props) with time-specific values:

<TypeTable
  type="{
  value: { type: &#x22;TimeValue | null&#x22;, description: &#x22;Controlled value: Time, CalendarDateTime or ZonedDateTime.&#x22; },
  defaultValue: { type: &#x22;TimeValue | null&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: TimeValue | null) => void&#x22;, description: &#x22;Receives the same type you passed in.&#x22; },
  granularity: { type: '&#x22;hour&#x22; | &#x22;minute&#x22; | &#x22;second&#x22;', default: '&#x22;minute&#x22;', description: &#x22;Smallest unit shown.&#x22; },
  hourCycle: { type: &#x22;12 | 24&#x22;, description: &#x22;Overrides the locale's hour cycle.&#x22; },
  placeholderValue: { type: &#x22;TimeValue&#x22;, description: &#x22;Where arrow keys start when empty. Defaults to 12:00 AM / 00:00.&#x22; },
  minValue: { type: &#x22;TimeValue | null&#x22;, description: &#x22;Earliest valid time.&#x22; },
  maxValue: { type: &#x22;TimeValue | null&#x22;, description: &#x22;Latest valid time.&#x22; },
  hideTimeZone: { type: &#x22;boolean&#x22;, description: &#x22;Hides the time zone segment of zoned values.&#x22; },
  shouldForceLeadingZeros: { type: &#x22;boolean&#x22;, description: &#x22;Always zero-pads the hour.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`TimeField`](https://react-aria.adobe.com/TimeField#api).

### DateInput

The segmented input used by both fields. Use it inside React Aria's `DateField` or `TimeField` for custom layouts.

<TypeTable
  type="{
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  slot: { type: &#x22;string&#x22;, description: 'e.g. &#x22;start&#x22; / &#x22;end&#x22; inside a DateRangePicker.' },
  className: { type: &#x22;string | ((state: DateInputRenderProps) => string)&#x22; },
}"
/>

## Related

* [Date Picker](/docs/components/date-picker) — a date field with a calendar popover, and date ranges.
* [Calendar](/docs/components/calendar) — an inline month grid.
* [Number Field](/docs/components/number-field) — the same stepper interaction for numbers.
* [Text Field](/docs/components/text-field) — shares the field variants and sizes.

---

# Date Picker

Source: https://desyne.dev/docs/components/date-picker

> A segmented date field with a calendar popover, for single dates, dates with a time, or date ranges. Users can type or pick; both stay in sync, with min/max bounds, unavailable dates, validation and native form submission built in.

```tsx title="date-picker/demo.tsx"
"use client";

import { DatePicker } from "@/components/ui/date-picker";

export default function DatePickerDemo() {
  return <DatePicker label="Due date" className="w-full max-w-60" />;
}
```

## Installation

```bash
npx shadcn@latest add @desyne/date-picker
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { DatePicker, DateRangePicker } from "@/components/ui/date-picker";
```

```tsx
<DatePicker label="Due date" />
<DateRangePicker label="Trip dates" />
```

<Callout title="Values are @internationalized/date objects">
  `value` is a `CalendarDate` (or `CalendarDateTime` / `ZonedDateTime` when you
  need a time), and ranges are `{ start, end }`. Create values with `today()`,
  `parseDate()` or `parseZonedDateTime()` from
  [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/),
  and store them with `value.toString()`.
</Callout>

### When to use

* Date Picker — the default for dates in forms. Typing is fast for known dates; the calendar helps with relative ones ("the second Friday").
* Date Range Picker — a start and end date in one field: bookings, reports, leave requests.
* [Date Field](/docs/components/date-field) — typed entry only, for dates far from today (birthdays) where a calendar would need many clicks.
* [Calendar](/docs/components/calendar) — an always-visible grid, when there's room on the page.

## Anatomy

```tsx
<DatePicker>                 {/* or <DateRangePicker> */}
  <Label />
  <FieldGroup>               {/* field chrome */}
    <DateInput />            {/* segments; start + end for ranges */}
    <Button />               {/* opens the calendar */}
  </FieldGroup>
  <Description />
  <FieldError />
  <Popover>
    <Dialog>
      <Calendar />           {/* or <RangeCalendar> */}
    </Dialog>
  </Popover>
</DatePicker>
```

| Part                             | Renders                      | Notes                                                                                                                                                      |
| -------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DatePicker`                     | `<div>`                      | Root. `data-slot="date-picker"`.                                                                                                                           |
| `DateRangePicker`                | `<div>`                      | Root for ranges. `data-slot="date-range-picker"`.                                                                                                          |
| Group                            | `<div role="group">`         | [`FieldGroup`](/docs/components/text-field) with the shared `variant` / `size` styles. Highlights while the popover is open.                               |
| Date input                       | `<div>`                      | Segmented input, styled with `dateSegmentStyles`. Ranges render a `start` and `end` input with an arrow between.                                           |
| Trigger                          | `<button>`                   | Ghost icon [`Button`](/docs/components/button) with a calendar icon.                                                                                       |
| Label / Description / FieldError | `<span>`                     | Rendered from `label`, `description` and validation.                                                                                                       |
| Popover                          | `Popover` › `Dialog`         | Placed `bottom start`, flips when there's no room.                                                                                                         |
| Calendar                         | `Calendar` / `RangeCalendar` | The same [Calendar](/docs/components/calendar). Inherits `minValue`, `maxValue`, `isDateUnavailable`, `firstDayOfWeek` and `pageBehavior` from the picker. |

## Examples

### Controlled

`value` and `onChange` own the value; set it to `null` to clear.

Example `date-picker/controlled`: source in https://desyne.dev/docs/components/date-picker.md

### Range

`DateRangePicker` edits a `{ start, end }` range with two segmented inputs and a `RangeCalendar`. Picking in the calendar sets both at once.

Example `date-picker/range`: source in https://desyne.dev/docs/components/date-picker.md

### Variants

Example `date-picker/variants`: source in https://desyne.dev/docs/components/date-picker.md

### Sizes

Example `date-picker/sizes`: source in https://desyne.dev/docs/components/date-picker.md

### Min and max

Dates outside `minValue` / `maxValue` are disabled in the calendar, and typed values outside them are flagged invalid with a localized message. Here `validationBehavior="aria"` shows the error straight away; with the default `native` behavior it appears after the value changes or the form is submitted.

Example `date-picker/validation`: source in https://desyne.dev/docs/components/date-picker.md

### Month and year dropdowns

`captionLayout`, `fromYear` and `toYear` are passed to the calendar in the popover (see [Calendar](/docs/components/calendar#month-and-year-dropdowns)). Use `captionLayout="dropdown"` for dates years away from today, like a date of birth, so nobody has to click back month by month. `placeholderValue` sets the month the calendar opens on.

Example `date-picker/birthday`: source in https://desyne.dev/docs/components/date-picker.md

The range picker takes the same props. Here the year list is limited to this year and next by `minValue` and `maxValue`.

Example `date-picker/booking`: source in https://desyne.dev/docs/components/date-picker.md

### Unavailable dates

`isDateUnavailable` strikes dates through in the calendar and marks a typed unavailable date invalid.

Example `date-picker/unavailable`: source in https://desyne.dev/docs/components/date-picker.md

### Date and time

With `granularity="minute"` (or `hour` / `second`) the field adds time segments. The calendar picks the date and keeps the time. Use a `ZonedDateTime` for a specific time zone, `hideTimeZone` to hide its abbreviation, and `hourCycle` to force a 12- or 24-hour clock.

Example `date-picker/date-time`: source in https://desyne.dev/docs/components/date-picker.md

### Range validation

`validate` receives the whole range. Combine it with `isRequired` and `minValue`; with `validationBehavior="aria"` on the form, errors update live.

Example `date-picker/range-validation`: source in https://desyne.dev/docs/components/date-picker.md

### Form submission

`name` submits a `DatePicker` value as an ISO 8601 string. `DateRangePicker` submits two fields, named with `startName` and `endName`.

Example `date-picker/form`: source in https://desyne.dev/docs/components/date-picker.md

### Locales and first day of the week

Format, segment order and the calendar's first weekday follow the locale. Wrap pickers in `I18nProvider` to set one, or override the week start with `firstDayOfWeek`.

Example `date-picker/locales`: source in https://desyne.dev/docs/components/date-picker.md

### Disabled and read-only

`isDisabled` disables the segments and the trigger. `isReadOnly` keeps the value focusable and readable, but the calendar can't open.

Example `date-picker/disabled`: source in https://desyne.dev/docs/components/date-picker.md

### Controlled open state

`isOpen` and `onOpenChange` control the popover, for example to open it from another button. `shouldCloseOnSelect={false}` keeps it open after a date is picked.

Example `date-picker/controlled-open`: source in https://desyne.dev/docs/components/date-picker.md

## Recipes

### Report period with presets

A preset [`Select`](/docs/components/select) next to a `DateRangePicker`. Choosing a preset fills the range; editing the range switches the preset to "Custom". `maxValue` blocks future dates.

Example `date-picker/recipe-report-range`: source in https://desyne.dev/docs/components/date-picker.md

### Hotel search

A native `<form>` with a required range (sold-out nights unavailable, the night count in the description), `startName` / `endName` for submission, and a [`NumberField`](/docs/components/number-field) for guests.

Example `date-picker/recipe-travel`: source in https://desyne.dev/docs/components/date-picker.md

### Quick picks

Shortcut buttons under the field for common due dates. They set the same controlled value the picker uses, and the active one is highlighted.

Example `date-picker/recipe-quick-dates`: source in https://desyne.dev/docs/components/date-picker.md

## Accessibility

* The field is a `role="group"` labelled by `label`. Segments are spin buttons, exactly like [Date Field](/docs/components/date-field#accessibility).
* The trigger button is labelled "Calendar" together with the field label, and is disabled when the picker is disabled or read-only.
* The popover is a dialog. Focus moves into the calendar when it opens (to the selected date, or today) and returns to the field when it closes.
* Everything outside the popover is hidden from screen readers while it's open.
* `description` and the error message are linked with `aria-describedby`; invalid pickers set `aria-invalid`.
* Always provide a label: `label`, `aria-label`, or `aria-labelledby`.

### Keyboard

| Key                                                       | Action                                                                            |
| --------------------------------------------------------- | --------------------------------------------------------------------------------- |
| <kbd>Alt</kbd>+<kbd>↓</kbd> / <kbd>Alt</kbd>+<kbd>↑</kbd> | Opens the calendar from the field                                                 |
| <kbd>Space</kbd> / <kbd>Enter</kbd>                       | Opens the calendar from the trigger button                                        |
| <kbd>←</kbd> / <kbd>→</kbd> / <kbd>↑</kbd> / <kbd>↓</kbd> | In the field: moves between / steps segments. In the calendar: moves between days |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                 | In the calendar: previous / next month                                            |
| <kbd>Enter</kbd> / <kbd>Space</kbd>                       | In the calendar: selects the focused date and closes                              |
| <kbd>Esc</kbd>                                            | Closes the calendar and returns focus to the field                                |

See [Calendar](/docs/components/calendar#keyboard) and [Date Field](/docs/components/date-field#keyboard) for the full lists.

## Styling

### Data attributes

On the `DatePicker` / `DateRangePicker` root (use `group-data-*/field:` for children):

| Attribute                                  | Present when                                            |
| ------------------------------------------ | ------------------------------------------------------- |
| `data-open`                                | The calendar popover is open (the group border uses it) |
| `data-focus-within` / `data-focus-visible` | Something inside has focus / keyboard focus             |
| `data-invalid`                             | Validation failed or `isInvalid` is set                 |
| `data-disabled`                            | `isDisabled` is true                                    |
| `data-readonly`                            | `isReadOnly` is true                                    |
| `data-required`                            | `isRequired` is true                                    |

On the field group:

| Attribute                                  | Present when                                        |
| ------------------------------------------ | --------------------------------------------------- |
| `data-hovered`                             | Hovered with a mouse                                |
| `data-focus-within` / `data-focus-visible` | A segment or the trigger has focus / keyboard focus |
| `data-invalid` / `data-disabled`           | Mirrors the picker                                  |

Segments expose the same attributes as in [Date Field](/docs/components/date-field#data-attributes), and calendar cells as in [Calendar](/docs/components/calendar#data-attributes).

### Slots

| `data-slot`                           | Element                     |
| ------------------------------------- | --------------------------- |
| `date-picker` / `date-range-picker`   | Root                        |
| `field-group`                         | Field chrome                |
| `button`                              | Calendar trigger            |
| `label`, `description`, `field-error` | Field text                  |
| `popover`                             | Calendar popover            |
| `calendar` / `range-calendar`         | Calendar inside the popover |

### Customizing

* `className` sizes and positions the whole picker (e.g. `w-full max-w-60`). It also accepts a function of the render props.
* The field chrome uses the shared `fieldVariants`, so pickers line up with text fields and selects of the same `size`.
* Segments use the exported `dateSegmentStyles` from [Date Field](/docs/components/date-field#style-helpers).
* The popover and calendar are fixed parts. For a different popover layout (presets beside the calendar, two months), compose React Aria's `DatePicker` with this library's [`Popover`](/docs/components/popover) and [`Calendar`](/docs/components/calendar).

## API Reference

### DatePicker

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text under the field.&#x22; },
  errorMessage: { type: &#x22;string | ((v: ValidationResult) => string)&#x22;, description: &#x22;Replaces the default validation message.&#x22; },
  variant: { type: '&#x22;outline&#x22; | &#x22;filled&#x22; | &#x22;underlined&#x22;', default: '&#x22;outline&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  value: { type: &#x22;DateValue | null&#x22;, description: &#x22;Controlled value.&#x22; },
  defaultValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Uncontrolled initial value.&#x22; },
  onChange: { type: &#x22;(value: DateValue | null) => void&#x22;, description: &#x22;Called when the value changes.&#x22; },
  granularity: { type: '&#x22;day&#x22; | &#x22;hour&#x22; | &#x22;minute&#x22; | &#x22;second&#x22;', default: '&#x22;day&#x22;', description: &#x22;Smallest unit shown in the field.&#x22; },
  minValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Earliest valid date. Earlier dates are disabled in the calendar.&#x22; },
  maxValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Latest valid date.&#x22; },
  isDateUnavailable: { type: &#x22;(date: DateValue) => boolean&#x22;, description: &#x22;Marks dates unavailable in the calendar and invalid when typed.&#x22; },
  placeholderValue: { type: &#x22;DateValue | null&#x22;, description: &#x22;Where arrow keys start when empty, and the calendar's initial month.&#x22; },
  firstDayOfWeek: { type: '&#x22;sun&#x22; | &#x22;mon&#x22; | &#x22;tue&#x22; | &#x22;wed&#x22; | &#x22;thu&#x22; | &#x22;fri&#x22; | &#x22;sat&#x22;', description: &#x22;Overrides the locale's first day of the week.&#x22; },
  pageBehavior: { type: '&#x22;visible&#x22; | &#x22;single&#x22;', default: '&#x22;visible&#x22;', description: &#x22;Calendar paging behavior.&#x22; },
  captionLayout: { type: '&#x22;label&#x22; | &#x22;dropdown&#x22; | &#x22;dropdown-months&#x22; | &#x22;dropdown-years&#x22;', default: '&#x22;label&#x22;', description: &#x22;Calendar header: a month heading, or month and/or year selects.&#x22; },
  fromYear: { type: &#x22;number&#x22;, description: &#x22;First year in the calendar's year select. Defaults to minValue's year, or 100 years ago.&#x22; },
  toYear: { type: &#x22;number&#x22;, description: &#x22;Last year in the calendar's year select. Defaults to maxValue's year, or 10 years ahead.&#x22; },
  hourCycle: { type: &#x22;12 | 24&#x22;, description: &#x22;Overrides the locale's hour cycle.&#x22; },
  hideTimeZone: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Hides the time zone of zoned values.&#x22; },
  shouldForceLeadingZeros: { type: &#x22;boolean&#x22;, description: &#x22;Always zero-pads month, day and hour.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state of the calendar.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the calendar opens or closes.&#x22; },
  shouldCloseOnSelect: { type: &#x22;boolean | (() => boolean)&#x22;, default: &#x22;true&#x22;, description: &#x22;Close the calendar after a date is picked.&#x22; },
  isRequired: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Requires a value before the form can submit.&#x22; },
  isInvalid: { type: &#x22;boolean&#x22;, description: &#x22;Forces the invalid state.&#x22; },
  validate: { type: &#x22;(value: DateValue) => string | string[] | true | null | undefined&#x22;, description: &#x22;Custom validation. Return an error message to mark the field invalid.&#x22; },
  validationBehavior: { type: '&#x22;native&#x22; | &#x22;aria&#x22;', default: '&#x22;native&#x22;', description: &#x22;native blocks submit and uses browser messages; aria shows errors live.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  isReadOnly: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, description: &#x22;Focuses the first segment on mount.&#x22; },
  name: { type: &#x22;string&#x22;, description: &#x22;Submits the value as an ISO 8601 string with forms.&#x22; },
  form: { type: &#x22;string&#x22;, description: &#x22;Id of the form this field belongs to.&#x22; },
  autoComplete: { type: &#x22;string&#x22;, description: &#x22;Autofill hint for the hidden date input.&#x22; },
  className: { type: &#x22;string | ((state: DatePickerRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`DatePicker`](https://react-aria.adobe.com/DatePicker#api).

### DateRangePicker

Accepts the same props as `DatePicker`, with range values:

<TypeTable
  type="{
  value: { type: &#x22;RangeValue<DateValue> | null&#x22;, description: &#x22;Controlled range: { start, end }.&#x22; },
  defaultValue: { type: &#x22;RangeValue<DateValue> | null&#x22;, description: &#x22;Uncontrolled initial range.&#x22; },
  onChange: { type: &#x22;(range: RangeValue<DateValue> | null) => void&#x22;, description: &#x22;Called when the range changes.&#x22; },
  validate: { type: &#x22;(range: RangeValue<DateValue>) => string | string[] | true | null | undefined&#x22;, description: &#x22;Custom validation of the whole range.&#x22; },
  isDateUnavailable: { type: &#x22;(date: DateValue, anchorDate: CalendarDate | null) => boolean&#x22;, description: &#x22;Also receives the first date picked in the calendar.&#x22; },
  allowsNonContiguousRanges: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Allows a range to include unavailable dates.&#x22; },
  startName: { type: &#x22;string&#x22;, description: &#x22;Form field name for the start date.&#x22; },
  endName: { type: &#x22;string&#x22;, description: &#x22;Form field name for the end date.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`DateRangePicker`](https://react-aria.adobe.com/DateRangePicker#api).

## Related

* [Calendar](/docs/components/calendar) — the calendar on its own, including multiple months and multi-date selection.
* [Date Field](/docs/components/date-field) — typed dates and times, and `TimeField`.
* [Popover](/docs/components/popover) — for building custom picker layouts.
* [Select](/docs/components/select) — pairs well with range pickers for presets.

---

# Dialog

Source: https://desyne.dev/docs/components/dialog

> A modal window that interrupts the page for a focused task, form or confirmation. Traps focus, locks scroll, restores focus on close, and supports alert, full-screen and controlled modes.

```tsx title="dialog/demo.tsx"
"use client";

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { TextField } from "@/components/ui/text-field";

export default function DialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline">Edit profile</Button>
      <DialogContent>
        {({ close }) => (
          <Form
            className="grid gap-5"
            onSubmit={(e) => {
              e.preventDefault();
              close();
            }}
          >
            <DialogHeader>
              <DialogTitle>Edit profile</DialogTitle>
              <DialogDescription>
                Update how your name appears to your team.
              </DialogDescription>
            </DialogHeader>
            <div className="grid gap-4">
              <TextField
                label="Name"
                defaultValue="Nischal Timalsina"
                autoFocus
              />
              <TextField label="Username" prefix="@" defaultValue="nischal" />
            </div>
            <DialogFooter>
              <DialogClose>Cancel</DialogClose>
              <Button type="submit">Save changes</Button>
            </DialogFooter>
          </Form>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/dialog
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
```

```tsx
<DialogTrigger>
  <Button>Open</Button>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
    {/* content */}
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <Button>Confirm</Button>
    </DialogFooter>
  </DialogContent>
</DialogTrigger>
```

`DialogTrigger` connects the first child (any pressable, usually a [`Button`](/docs/components/button)) to the `DialogContent` after it. No state or refs needed.

### When to use

* Dialog — a short, self-contained task that needs the user's full attention: a form, a confirmation, a detail view.
* [Sheet](/docs/components/sheet) — longer or secondary content that slides in from an edge and can stay open while users reference the page.
* [Popover](/docs/components/popover) — lightweight, non-modal content anchored to a trigger.
* [Toast](/docs/components/toast) — feedback that doesn't need a response.

Avoid dialogs that open other dialogs; prefer a multi-step flow inside one dialog.

## Anatomy

```tsx
<DialogTrigger>
  <Button />                       {/* trigger */}
  <DialogContent>                  {/* overlay + modal + dialog */}
    <DialogIcon />                 {/* optional status icon (alert dialogs) */}
    <DialogHeader>
      <DialogTitle />              {/* accessible name */}
      <DialogDescription />
    </DialogHeader>
    <DialogBody />                 {/* optional scrollable region */}
    <DialogFooter>
      <DialogClose />              {/* button that closes the dialog */}
    </DialogFooter>
  </DialogContent>
</DialogTrigger>
```

| Part                | Renders                             | Notes                                                                                   |
| ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- |
| `DialogTrigger`     | —                                   | Manages open state and wires the trigger to the dialog.                                 |
| `DialogContent`     | `ModalOverlay` › `Modal` › `Dialog` | Backdrop, centered panel and the `role="dialog"` element. Adds a close icon by default. |
| `DialogHeader`      | `<div>`                             | Stacks title and description; leaves room for the close icon.                           |
| `DialogTitle`       | `Heading` (`slot="title"`)          | Becomes the dialog's accessible name.                                                   |
| `DialogDescription` | `<p>`                               | Supporting text.                                                                        |
| `DialogIcon`        | `<div>`                             | Tinted circular icon for alert dialogs.                                                 |
| `DialogBody`        | `<div>`                             | Optional. Takes the remaining height and scrolls when content overflows.                |
| `DialogFooter`      | `<div>`                             | Actions. Stacked (primary on top) on mobile, right-aligned on larger screens.           |
| `DialogClose`       | `Button slot="close"`               | Any button with `slot="close"` closes the dialog. Defaults to `outline`.                |
| `DialogCloseIcon`   | `<button>`                          | The top-right ✕. Rendered automatically unless `showCloseButton={false}`.               |

## Examples

### Alert dialog

`role="alertdialog"` is for confirmations that need an explicit decision. It can't be dismissed by clicking outside and hides the close icon. `DialogIcon` adds a tinted status icon.

Example `dialog/alert-dialog`: source in https://desyne.dev/docs/components/dialog.md

### Sizes

`sm` (384px), `md` (512px, default), `lg` (672px), `xl` (896px) set the maximum width. The dialog shrinks to fit smaller viewports.

Example `dialog/sizes`: source in https://desyne.dev/docs/components/dialog.md

### Full screen

`size="full"` fills the viewport with a 1rem margin — useful for editors, previews and complex forms on small screens. Give the main element `flex-1` to fill the space between header and footer.

Example `dialog/fullscreen`: source in https://desyne.dev/docs/components/dialog.md

### Scrollable content

Dialogs never grow taller than the viewport. Wrap long content in `DialogBody` and it scrolls while the header and footer stay put. Pass a `max-h-*` class to `DialogContent` for a shorter cap.

Example `dialog/scrollable`: source in https://desyne.dev/docs/components/dialog.md

### Forms

Wrap the content in a React Aria `Form` and use the render-function child, `({ close }) => …`, to close the dialog after a successful submit.

```tsx title="dialog/demo.tsx"
"use client";

import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import {
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import { TextField } from "@/components/ui/text-field";

export default function DialogDemo() {
  return (
    <DialogTrigger>
      <Button variant="outline">Edit profile</Button>
      <DialogContent>
        {({ close }) => (
          <Form
            className="grid gap-5"
            onSubmit={(e) => {
              e.preventDefault();
              close();
            }}
          >
            <DialogHeader>
              <DialogTitle>Edit profile</DialogTitle>
              <DialogDescription>
                Update how your name appears to your team.
              </DialogDescription>
            </DialogHeader>
            <div className="grid gap-4">
              <TextField
                label="Name"
                defaultValue="Nischal Timalsina"
                autoFocus
              />
              <TextField label="Username" prefix="@" defaultValue="nischal" />
            </div>
            <DialogFooter>
              <DialogClose>Cancel</DialogClose>
              <Button type="submit">Save changes</Button>
            </DialogFooter>
          </Form>
        )}
      </DialogContent>
    </DialogTrigger>
  );
}
```

### Validation and async submit

Field validation runs before `onSubmit`. Show `isPending` on the submit button while the request runs, then close and confirm with a [toast](/docs/components/toast).

Example `dialog/form-validation`: source in https://desyne.dev/docs/components/dialog.md

### Controlled

Render `DialogContent` without a trigger and control it with `isOpen` and `onOpenChange`. Use this to open a dialog from a [menu](/docs/components/menu) item, a keyboard shortcut or after an async event. Focus returns to the element that was focused before opening.

Example `dialog/controlled`: source in https://desyne.dev/docs/components/dialog.md

### Non-dismissable

`isDismissable={false}` ignores outside clicks, `isKeyboardDismissDisabled` ignores <kbd>Esc</kbd>, and `showCloseButton={false}` hides the ✕. Use sparingly — users should always have a visible way out.

Example `dialog/non-dismissable`: source in https://desyne.dev/docs/components/dialog.md

## Recipes

### Type to confirm

For irreversible, high-impact actions, require the user to type the resource name before the destructive button is enabled.

Example `dialog/recipe-type-to-confirm`: source in https://desyne.dev/docs/components/dialog.md

### Invite members

A small form that builds a list, with per-row role [`Select`](/docs/components/select)s inside the dialog.

Example `dialog/recipe-invite`: source in https://desyne.dev/docs/components/dialog.md

### Multi-step wizard

Keep one dialog open and swap its body. A [`ProgressBar`](/docs/components/progress-bar) and "Step x of y" give orientation; Back and Continue replace a stack of nested dialogs.

Example `dialog/recipe-wizard`: source in https://desyne.dev/docs/components/dialog.md

## Accessibility

* Focus moves into the dialog on open (to the first focusable element, or one with `autoFocus`), stays trapped inside, and returns to the trigger on close.
* Page scroll is locked while open, and content outside the dialog is hidden from screen readers with `aria-hidden`.
* `DialogTitle` provides the accessible name. Without a visible title, pass `aria-label` to `DialogContent`.
* `role="alertdialog"` tells screen readers the dialog needs an immediate response.
* Put `autoFocus` on the least destructive action in alert dialogs, or on the first field in forms.
* Nested overlays (selects, menus, popovers) inside a dialog work as expected; <kbd>Esc</kbd> closes the innermost one first.

### Keyboard

| Key                                              | Action                                                                         |
| ------------------------------------------------ | ------------------------------------------------------------------------------ |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Cycles focus within the dialog                                                 |
| <kbd>Esc</kbd>                                   | Closes the dialog (unless `isKeyboardDismissDisabled` or `role="alertdialog"`) |

## Styling

### Data attributes

| Attribute                    | On               | Present when                 |
| ---------------------------- | ---------------- | ---------------------------- |
| `data-entering`              | overlay, content | Opening animation is running |
| `data-exiting`               | overlay, content | Closing animation is running |
| `data-slot="dialog-overlay"` | backdrop         | Always                       |
| `data-slot="dialog-content"` | panel            | Always                       |
| `data-slot="dialog-body"`    | body             | When `DialogBody` is used    |

Enter and exit animations use `tw-animate-css` classes keyed off `data-entering` and `data-exiting`, so React Aria waits for them to finish before unmounting.

### Customizing

* `className` on `DialogContent` styles the panel (width, height, padding, radius).
* The backdrop uses the exported `overlayStyles` string; reuse it for your own modal surfaces.
* The panel is a flex column capped at the viewport height; the inner `Dialog` is `flex flex-col gap-4 p-6` and scrolls as a fallback if you don't use `DialogBody`.
* The inner `Dialog` padding is `p-6`. Override with `[&>[role=dialog]]:p-0` on `DialogContent` for edge-to-edge content like images.

## API Reference

### DialogTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;A pressable trigger followed by DialogContent.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the dialog opens or closes.&#x22; },
}"
/>

### DialogContent

<TypeTable
  type="{
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22; | &#x22;full&#x22;', default: '&#x22;md&#x22;', description: &#x22;Maximum width (full fills the viewport).&#x22; },
  role: { type: '&#x22;dialog&#x22; | &#x22;alertdialog&#x22;', default: '&#x22;dialog&#x22;', description: &#x22;alertdialog also disables outside-click dismissal and the close icon.&#x22; },
  showCloseButton: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the ✕ button (never shown for alert dialogs).&#x22; },
  isDismissable: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Close when clicking outside.&#x22; },
  isKeyboardDismissDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Ignore the Esc key.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state, when used without a DialogTrigger.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22; },
  shouldCloseOnInteractOutside: { type: &#x22;(element: Element) => boolean&#x22;, description: &#x22;Fine-grained control over which outside clicks close the dialog.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there is no DialogTitle.&#x22; },
  children: { type: &#x22;ReactNode | ((opts: { close: () => void }) => ReactNode)&#x22;, description: &#x22;Content, or a function that receives close().&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the modal panel.&#x22; },
}"
/>

### DialogIcon

<TypeTable
  type="{
  tone: { type: '&#x22;primary&#x22; | &#x22;danger&#x22; | &#x22;warning&#x22; | &#x22;success&#x22; | &#x22;info&#x22;', default: '&#x22;primary&#x22;' },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;An icon, sized to 20px.&#x22; },
}"
/>

### DialogClose

A [`Button`](/docs/components/button) with `slot="close"`. Accepts every button prop.

<TypeTable
  type="{
  variant: { type: &#x22;ButtonProps['variant']&#x22;, default: '&#x22;outline&#x22;' },
}"
/>

### DialogTitle

Accepts every prop of React Aria's [`Heading`](https://react-aria.adobe.com/Dialog#heading), including `level` to change the heading element.

### DialogHeader / DialogBody / DialogFooter / DialogDescription

Accept every prop of `<div>` / `<div>` / `<div>` / `<p>`.

## Related

* [Sheet](/docs/components/sheet) — a dialog that slides in from the edge.
* [Popover](/docs/components/popover) — non-modal content anchored to a trigger.
* [Command Palette](/docs/components/command-palette) — a searchable dialog of actions.
* [Toast](/docs/components/toast) — non-blocking feedback after the dialog closes.

---

# Sheet

Source: https://desyne.dev/docs/components/sheet

> A modal panel that slides in from any edge of the screen, for navigation, filters, carts and detail views. Built on the same modal as Dialog, so it traps focus, locks scroll and restores focus on close.

```tsx title="sheet/demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import {
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet";
import { TextField } from "@/components/ui/text-field";

export default function SheetDemo() {
  return (
    <SheetTrigger>
      <Button variant="outline">Edit profile</Button>
      <SheetContent>
        <SheetHeader>
          <SheetTitle>Edit profile</SheetTitle>
          <SheetDescription>
            Changes are visible to everyone in your workspace.
          </SheetDescription>
        </SheetHeader>
        <div className="grid gap-4 p-5">
          <TextField label="Name" defaultValue="Sofia Martins" />
          <TextField label="Username" prefix="@" defaultValue="sofiam" />
          <TextField label="Title" defaultValue="Product designer" />
        </div>
        <SheetFooter>
          <SheetClose>Cancel</SheetClose>
          <SheetClose variant="solid">Save changes</SheetClose>
        </SheetFooter>
      </SheetContent>
    </SheetTrigger>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/sheet
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import {
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@/components/ui/sheet";
```

```tsx
<SheetTrigger>
  <Button>Open</Button>
  <SheetContent side="right">
    <SheetHeader>
      <SheetTitle>Title</SheetTitle>
      <SheetDescription>Description</SheetDescription>
    </SheetHeader>
    <div className="p-5">{/* content */}</div>
    <SheetFooter>
      <SheetClose>Cancel</SheetClose>
      <Button>Save</Button>
    </SheetFooter>
  </SheetContent>
</SheetTrigger>
```

`SheetTrigger` connects the first child (any pressable, usually a [`Button`](/docs/components/button)) to the `SheetContent` after it. No state or refs needed.

<Callout title="The body is yours to pad">
  `SheetHeader` and `SheetFooter` bring their own padding and borders, but the
  panel itself has none, so full-bleed lists and navigation are easy. Wrap the
  content between them in a `div` with `p-5`, and add
  `min-h-0 flex-1 overflow-y-auto` when it can grow taller than the screen.
</Callout>

### When to use

* Sheet — secondary or longer content that relates to the current page: filters, a cart, a record's details, mobile navigation.
* [Dialog](/docs/components/dialog) — a short, focused task or confirmation that belongs in the middle of the screen.
* [Popover](/docs/components/popover) — small, non-blocking content anchored to its trigger.
* [Sidebar](/docs/components/sidebar) — persistent navigation that stays on screen.

## Anatomy

```tsx
<SheetTrigger>
  <Button />                   {/* trigger */}
  <SheetContent>               {/* overlay + sliding panel + dialog */}
    <SheetHeader>
      <SheetTitle />           {/* accessible name */}
      <SheetDescription />
    </SheetHeader>
    <div />                    {/* your content */}
    <SheetFooter>
      <SheetClose />           {/* button that closes the sheet */}
    </SheetFooter>
  </SheetContent>
</SheetTrigger>
```

| Part               | Renders                             | Notes                                                                                                                         |
| ------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `SheetTrigger`     | —                                   | Manages open state and wires the trigger to the sheet. Same as `DialogTrigger`.                                               |
| `SheetContent`     | `ModalOverlay` › `Modal` › `Dialog` | Backdrop, sliding panel and the `role="dialog"` element, a flex column that fills the panel. Adds a close icon by default.    |
| `SheetHeader`      | `<div>`                             | Title and description, with `p-5`, a bottom border and room for the close icon.                                               |
| `SheetTitle`       | `Heading` (`slot="title"`)          | Becomes the sheet's accessible name.                                                                                          |
| `SheetDescription` | `<p>`                               | Supporting text.                                                                                                              |
| `SheetFooter`      | `<div>`                             | Actions pinned to the bottom with `mt-auto` and a top border. Stacked (primary on top) on mobile, right-aligned from `sm` up. |
| `SheetClose`       | `Button slot="close"`               | Any button with `slot="close"` closes the sheet. Defaults to `outline`.                                                       |
| Close icon         | `<button>`                          | The top-right ✕. Rendered unless `showCloseButton={false}`.                                                                   |

## Examples

### Sides

`right` (default) and `left` suit detail panels and navigation; `bottom` suits mobile action sheets; `top` suits announcements and search. Each side slides in from its own edge.

Example `sheet/sides`: source in https://desyne.dev/docs/components/sheet.md

### Sizes

`size` sets the maximum width of `left` and `right` sheets from the `sm` breakpoint up: `sm` (320px), `md` (384px, default) and `lg` (576px). On phones they take 75% of the screen. `top` and `bottom` sheets are full width and size to their content.

Example `sheet/sizes`: source in https://desyne.dev/docs/components/sheet.md

### Scrollable content

The panel is always the full height of the screen. Give the content `min-h-0 flex-1 overflow-y-auto` so it scrolls while the header and footer stay in place.

Example `sheet/scrollable`: source in https://desyne.dev/docs/components/sheet.md

### Forms

Use the render-function child, `({ close }) => …`, and wrap everything in a React Aria `Form` with `flex min-h-0 flex-1 flex-col` so the footer stays at the bottom. Validation runs before `onSubmit`; close the sheet once the request succeeds.

Example `sheet/form`: source in https://desyne.dev/docs/components/sheet.md

### Controlled

Render `SheetContent` without a trigger and control it with `isOpen` and `onOpenChange`. Use this to open a detail panel from a list row, a table or a keyboard shortcut. Focus returns to the row that opened it.

Example `sheet/controlled`: source in https://desyne.dev/docs/components/sheet.md

### Non-dismissable

`isDismissable={false}` ignores backdrop clicks, `isKeyboardDismissDisabled` ignores <kbd>Esc</kbd>, and `showCloseButton={false}` hides the ✕. Reserve this for work that must finish, and always leave a visible way out once it has.

Example `sheet/non-dismissable`: source in https://desyne.dev/docs/components/sheet.md

## Recipes

### Filter panel

A left sheet with [`CheckboxGroup`](/docs/components/checkbox), [`Slider`](/docs/components/slider), [`RadioGroup`](/docs/components/radio-group) and [`Switch`](/docs/components/switch). Edits go into a draft that's only applied on "Show results"; "Reset" restores the defaults, and the trigger shows how many filters are active.

Example `sheet/recipe-filters`: source in https://desyne.dev/docs/components/sheet.md

### Mobile navigation

A hamburger button that opens a left sheet with navigation links, an account footer and no header. Without a `SheetTitle`, the sheet is named with `aria-label`. Links close the sheet through `close()` from the render function.

Example `sheet/recipe-mobile-nav`: source in https://desyne.dev/docs/components/sheet.md

### Shopping cart

A cart with quantity steppers and a scrollable item list, and a footer that stacks the subtotal above a full-width checkout button.

Example `sheet/recipe-cart`: source in https://desyne.dev/docs/components/sheet.md

## Accessibility

* Focus moves into the sheet on open (to the first focusable element, or one with `autoFocus`), stays trapped inside, and returns to the trigger on close.
* Page scroll is locked while open, and content outside is hidden from screen readers.
* `SheetTitle` provides the accessible name. Without a visible title, pass `aria-label` to `SheetContent`.
* The close icon has `aria-label="Close"`.
* Nested overlays (selects, menus, popovers) inside a sheet work as expected; <kbd>Esc</kbd> closes the innermost one first.

### Keyboard

| Key                                              | Action                                                |
| ------------------------------------------------ | ----------------------------------------------------- |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Cycles focus within the sheet                         |
| <kbd>Esc</kbd>                                   | Closes the sheet (unless `isKeyboardDismissDisabled`) |

## Styling

### Data attributes

| Attribute       | On             | Present when                 |
| --------------- | -------------- | ---------------------------- |
| `data-entering` | overlay, panel | Opening animation is running |
| `data-exiting`  | overlay, panel | Closing animation is running |

Enter and exit animations are `tw-animate-css` slide classes keyed off these attributes (300ms in, 200ms out), so React Aria waits for them before unmounting.

### Slots

| `data-slot`                          | Element                                    |
| ------------------------------------ | ------------------------------------------ |
| `sheet-overlay`                      | Backdrop                                   |
| `sheet-content`                      | Sliding panel                              |
| `sheet-header`                       | Header                                     |
| `sheet-footer`                       | Footer                                     |
| `dialog-title`, `dialog-description` | Title and description (shared with Dialog) |

### Customizing

* `className` on `SheetContent` styles the panel: override the width with `sm:max-w-md`, or cap a bottom sheet with `max-h-[80dvh]`.
* The panel is `fixed flex flex-col bg-popover` with a border on the inner edge. The inner dialog is a `relative flex h-full flex-col`, so children stack from top to bottom and `SheetFooter` sits at the bottom. It scrolls as a whole as a fallback when you don't give the content its own scroll area.
* The backdrop reuses `overlayStyles` from [Dialog](/docs/components/dialog#customizing).

### `sheetVariants`

The `tailwind-variants` function behind the panel. Use it to build your own edge panels.

```tsx
import { sheetVariants } from "@/components/ui/sheet";

sheetVariants({ side: "left", size: "lg" });
```

## API Reference

### SheetTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;A pressable trigger followed by SheetContent.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the sheet opens or closes.&#x22; },
}"
/>

### SheetContent

<TypeTable
  type="{
  side: { type: '&#x22;top&#x22; | &#x22;right&#x22; | &#x22;bottom&#x22; | &#x22;left&#x22;', default: '&#x22;right&#x22;', description: &#x22;Edge the sheet slides in from.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Max width of left and right sheets from the sm breakpoint: 320, 384 or 576px. No effect on top and bottom sheets.&#x22; },
  showCloseButton: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the ✕ button in the top-right corner.&#x22; },
  isDismissable: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Close when clicking the backdrop.&#x22; },
  isKeyboardDismissDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Ignore the Esc key.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state, when used without a SheetTrigger.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the sheet opens or closes.&#x22; },
  shouldCloseOnInteractOutside: { type: &#x22;(element: Element) => boolean&#x22;, description: &#x22;Fine-grained control over which outside clicks close the sheet.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there is no SheetTitle.&#x22; },
  children: { type: &#x22;ReactNode | ((opts: { close: () => void }) => ReactNode)&#x22;, description: &#x22;Content, or a function that receives close().&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the sliding panel.&#x22; },
}"
/>

Also accepts the other props of React Aria's [`ModalOverlay`](https://react-aria.adobe.com/Modal#api).

### SheetClose

A [`Button`](/docs/components/button) with `slot="close"`. Accepts every button prop.

<TypeTable
  type="{
  variant: { type: &#x22;ButtonProps['variant']&#x22;, default: '&#x22;outline&#x22;' },
}"
/>

### SheetTitle

Accepts every prop of React Aria's [`Heading`](https://react-aria.adobe.com/Dialog#heading), including `level` to change the heading element.

### SheetHeader / SheetFooter / SheetDescription

Accept every prop of `<div>` / `<div>` / `<p>`.

### sheetVariants

<TypeTable
  type="{
  side: { type: '&#x22;top&#x22; | &#x22;right&#x22; | &#x22;bottom&#x22; | &#x22;left&#x22;', default: '&#x22;right&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Dialog](/docs/components/dialog) — a centered modal for focused tasks.
* [Popover](/docs/components/popover) — non-modal content anchored to a trigger.
* [Sidebar](/docs/components/sidebar) — persistent app navigation.
* [Toast](/docs/components/toast) — confirm the result after the sheet closes.

---

# Popover

Source: https://desyne.dev/docs/components/popover

> Floating content anchored to a trigger, for small forms, details, pickers and notifications. Positions itself automatically, flips to stay on screen, moves focus in and restores it on close, with an optional arrow.

```tsx title="popover/demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import { NumberField } from "@/components/ui/number-field";
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";

export default function PopoverDemo() {
  return (
    <PopoverTrigger>
      <Button variant="outline">Dimensions</Button>
      <Popover>
        <PopoverDialog className="grid gap-4">
          <div className="grid gap-1.5">
            <PopoverTitle>Dimensions</PopoverTitle>
            <p className="text-muted-foreground text-sm">
              Set the size of the selected layer.
            </p>
          </div>
          <div className="grid grid-cols-2 gap-2">
            <NumberField label="Width" defaultValue={1200} minValue={1} />
            <NumberField label="Height" defaultValue={630} minValue={1} />
          </div>
        </PopoverDialog>
      </Popover>
    </PopoverTrigger>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/popover
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import {
  Popover,
  PopoverDialog,
  PopoverTitle,
  PopoverTrigger,
} from "@/components/ui/popover";
```

```tsx
<PopoverTrigger>
  <Button>Open</Button>
  <Popover>
    <PopoverDialog>
      <PopoverTitle>Title</PopoverTitle>
      {/* content */}
    </PopoverDialog>
  </Popover>
</PopoverTrigger>
```

`PopoverTrigger` connects the first child (any pressable, usually a [`Button`](/docs/components/button)) to the `Popover` after it. `Popover` is the positioned surface; `PopoverDialog` adds padding and dialog semantics so focus moves in and the content is announced.

<Callout title="Always wrap content in PopoverDialog">
  `Popover` on its own is just a positioned container. That's what
  [Menu](/docs/components/menu) and [Select](/docs/components/select) build on,
  because they bring their own roles. For anything else, put a
  `PopoverDialog` inside and name it with a `PopoverTitle` or an `aria-label`.
</Callout>

### When to use

* Popover — small, interactive content tied to a specific control: a quick form, a share panel, a detail card, a notification list.
* [Tooltip](/docs/components/tooltip) — a short, non-interactive label shown on hover or focus.
* [Menu](/docs/components/menu) — a list of actions.
* [Dialog](/docs/components/dialog) — a task that needs the user's full attention, or content too large for a popover.
* [Sheet](/docs/components/sheet) — longer secondary content that slides in from an edge.

## Anatomy

```tsx
<PopoverTrigger>
  <Button />                {/* trigger */}
  <Popover>                 {/* positioned surface, optional arrow */}
    <PopoverDialog>         {/* role="dialog", padding, focus management */}
      <PopoverTitle />      {/* accessible name */}
    </PopoverDialog>
  </Popover>
</PopoverTrigger>
```

| Part             | Renders                            | Notes                                                                                                                |
| ---------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `PopoverTrigger` | —                                  | Manages open state and wires the trigger to the popover. Same component as `DialogTrigger`.                          |
| `Popover`        | `<div>` (portal)                   | Positioned surface with border, shadow and enter/exit animations. Renders an `OverlayArrow` when `showArrow` is set. |
| `PopoverDialog`  | `<div role="dialog">`              | Content wrapper with `w-72 p-4`. Receives focus on open.                                                             |
| `PopoverTitle`   | `Heading` (`slot="title"`, `<h2>`) | Becomes the dialog's accessible name.                                                                                |

## Examples

### With arrow

`showArrow` adds an arrow that points at the trigger and rotates with the placement. The default offset grows from 4px to 10px to make room for it. Arrows help most when the trigger is small, like an info icon.

Example `popover/arrow`: source in https://desyne.dev/docs/components/popover.md

### Placement

`placement` sets the preferred side and alignment: `top`, `bottom`, `left`, `right`, `start`, `end`, plus combinations like `bottom start` or `top end`. The default is `bottom`. When there isn't room, the popover flips to the opposite side (disable with `shouldFlip={false}`).

Example `popover/placement`: source in https://desyne.dev/docs/components/popover.md

### Forms

`PopoverDialog` accepts a render function, `({ close }) => …`. Wrap a React Aria `Form` in it to validate the fields and close the popover after a successful submit.

Example `popover/form`: source in https://desyne.dev/docs/components/popover.md

### Controlled

Pass `isOpen` and `onOpenChange` to `PopoverTrigger` to own the open state, for example to close the popover after a choice or to open it from code.

Example `popover/controlled`: source in https://desyne.dev/docs/components/popover.md

### Custom anchor

Use `Popover` without a trigger by passing `triggerRef`, `isOpen` and `onOpenChange`. It then positions itself relative to any element, here a field, while a separate link opens it.

Example `popover/trigger-ref`: source in https://desyne.dev/docs/components/popover.md

### Rich content

Any pressable can be the trigger, like an inline name that opens a profile card with an [`Avatar`](/docs/components/avatar), a [`Badge`](/docs/components/badge) and actions. Popovers open on press, not hover, so the content stays reachable for keyboard and touch users.

Example `popover/profile-card`: source in https://desyne.dev/docs/components/popover.md

## Recipes

### Share panel

A copyable link, a [`Select`](/docs/components/select) for access level and an [`AvatarGroup`](/docs/components/avatar) of collaborators. Nested overlays like the select work inside a popover; <kbd>Esc</kbd> closes the innermost one first.

Example `popover/recipe-share`: source in https://desyne.dev/docs/components/popover.md

### Notifications

An icon button with an unread count opens a scrollable list with "Mark all read". The trigger's `aria-label` includes the count, since the badge is visual only. `p-0` on `PopoverDialog` lets the header and list run edge to edge.

Example `popover/recipe-notifications`: source in https://desyne.dev/docs/components/popover.md

### Feedback form

A small form with a [`TextareaField`](/docs/components/textarea) and an emoji [`ToggleButtonGroup`](/docs/components/toggle-button-group). The submit button shows `isPending` while the request runs, then the popover closes and a [toast](/docs/components/toast) confirms.

Example `popover/recipe-feedback`: source in https://desyne.dev/docs/components/popover.md

## Accessibility

* `PopoverDialog` renders `role="dialog"`. Focus moves into the popover on open (to an element with `autoFocus`, otherwise the popover itself) and returns to the trigger on close.
* Name the dialog with `PopoverTitle` or `aria-label`. Without either, React Aria falls back to labelling it by the trigger.
* The trigger gets `aria-expanded` and `aria-controls`, so screen readers announce that it opens a dialog.
* Popovers are modal for assistive tech: content outside is hidden from screen readers while open. `isNonModal` turns this off, but only use it for patterns designed for it.
* Clicking outside or pressing <kbd>Esc</kbd> closes the popover.

### Keyboard

| Key                                              | Action                                              |
| ------------------------------------------------ | --------------------------------------------------- |
| <kbd>Space</kbd> / <kbd>Enter</kbd>              | Opens the popover from the trigger                  |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus through the popover's content           |
| <kbd>Esc</kbd>                                   | Closes the popover and returns focus to the trigger |

## Styling

### Data attributes

On the `Popover`:

| Attribute             | Present when                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `data-placement`      | Always: the resolved side, `"top"`, `"bottom"`, `"left"` or `"right"` (after flipping)     |
| `data-trigger`        | Set to the component that opened it, e.g. `"DialogTrigger"`, `"MenuTrigger"` or `"Select"` |
| `data-entering`       | Opening animation is running                                                               |
| `data-exiting`        | Closing animation is running                                                               |
| `data-slot="popover"` | Always                                                                                     |

`PopoverDialog` has `data-slot="popover-dialog"` and `PopoverTitle` has `data-slot="popover-title"`.

### CSS variables

| Variable                 | Value                                                                               |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `--trigger-width`        | Width of the trigger, e.g. `min-w-(--trigger-width)` to match it                    |
| `--trigger-anchor-point` | The point on the trigger the popover is anchored to, useful as a `transform-origin` |

### Customizing

* `className` on `Popover` styles the surface; `className` on `PopoverDialog` sets the width and padding (defaults `w-72 p-4`).
* The slide direction of the enter animation follows `data-placement`, so the popover always grows away from its trigger.
* `popoverStyles` is exported: the class string for the surface (border, background, shadow, animations). Reuse it for custom floating elements.

```tsx
import { popoverStyles } from "@/components/ui/popover";
```

### Render props

`className` and `children` on `Popover` accept a function of its state:

```tsx
<Popover className={({ placement }) => (placement === "top" ? "mb-1" : "")}>
  …
</Popover>
```

## API Reference

### PopoverTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;A pressable trigger followed by a Popover.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the popover opens or closes.&#x22; },
}"
/>

### Popover

<TypeTable
  type="{
  showArrow: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Renders an arrow pointing at the trigger.&#x22; },
  placement: { type: &#x22;Placement&#x22;, default: '&#x22;bottom&#x22;', description: 'Preferred position, e.g. &#x22;top&#x22;, &#x22;bottom start&#x22;, &#x22;end top&#x22;.' },
  offset: { type: &#x22;number&#x22;, default: &#x22;4 (10 with showArrow)&#x22;, description: &#x22;Distance from the trigger along the main axis, in px.&#x22; },
  crossOffset: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Shift along the cross axis, in px.&#x22; },
  containerPadding: { type: &#x22;number&#x22;, default: &#x22;12&#x22;, description: &#x22;Minimum space to keep between the popover and the viewport edge.&#x22; },
  shouldFlip: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Flip to the opposite side when there isn't enough room.&#x22; },
  maxHeight: { type: &#x22;number&#x22;, description: &#x22;Caps the popover's height, in px.&#x22; },
  triggerRef: { type: &#x22;RefObject<Element | null>&#x22;, description: &#x22;Element to position against. Set automatically inside PopoverTrigger.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state, when used without PopoverTrigger.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the popover opens or closes.&#x22; },
  isKeyboardDismissDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Ignore the Esc key. Provide another way to close.&#x22; },
  shouldCloseOnInteractOutside: { type: &#x22;(element: Element) => boolean&#x22;, description: &#x22;Return false to keep the popover open for clicks on a given element.&#x22; },
  isNonModal: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Keep content outside accessible to screen readers. Rarely needed.&#x22; },
  boundaryElement: { type: &#x22;Element&#x22;, default: &#x22;document.body&#x22;, description: &#x22;Element that bounds the positioning.&#x22; },
  className: { type: &#x22;string | ((state: PopoverRenderProps) => string)&#x22;, description: &#x22;Classes for the surface, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: PopoverRenderProps) => ReactNode)&#x22;, description: &#x22;Usually a PopoverDialog.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Popover`](https://react-aria.adobe.com/Popover#api).

### PopoverDialog

<TypeTable
  type="{
  children: { type: &#x22;ReactNode | ((opts: { close: () => void }) => ReactNode)&#x22;, description: &#x22;Content, or a function that receives close().&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there is no PopoverTitle.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of an element that labels the dialog.&#x22; },
  role: { type: '&#x22;dialog&#x22; | &#x22;alertdialog&#x22;', default: '&#x22;dialog&#x22;', description: &#x22;ARIA role of the content.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the content wrapper (defaults to w-72 p-4).&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Dialog`](https://react-aria.adobe.com/Dialog#api).

### PopoverTitle

Accepts every prop of React Aria's [`Heading`](https://react-aria.adobe.com/Dialog#heading), including `level` to change the heading element (`<h2>` inside a dialog).

## Related

* [Tooltip](/docs/components/tooltip) — a short label on hover or focus.
* [Menu](/docs/components/menu) — a list of actions in a popover.
* [Dialog](/docs/components/dialog) — a centered modal for focused tasks.
* [Date Picker](/docs/components/date-picker) — a calendar in a popover.

---

# Tooltip

Source: https://desyne.dev/docs/components/tooltip

> A short label shown on hover or keyboard focus, for icon-only buttons, abbreviations and extra context. Tuned delays, a shared warm-up between tooltips, dark and light variants, and an arrow that follows the placement.

```tsx title="tooltip/demo.tsx"
"use client";

import { BookmarkPlusIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";

export default function TooltipDemo() {
  return (
    <TooltipTrigger>
      <Button variant="outline" size="icon" aria-label="Add to library">
        <BookmarkPlusIcon />
      </Button>
      <Tooltip>Add to library</Tooltip>
    </TooltipTrigger>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/tooltip
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { Tooltip, TooltipTrigger } from "@/components/ui/tooltip";
```

```tsx
<TooltipTrigger>
  <Button variant="ghost" size="icon" aria-label="Save">
    <SaveIcon />
  </Button>
  <Tooltip>Save</Tooltip>
</TooltipTrigger>
```

`TooltipTrigger` wraps a focusable trigger (a [`Button`](/docs/components/button), [`Link`](/docs/components/link), [`ToggleButton`](/docs/components/toggle-button) or any element inside React Aria's `Focusable`) and the `Tooltip` that describes it.

<Callout title="Tooltips supplement, they don't replace labels">
  The tooltip is linked to its trigger with `aria-describedby`, so it's read as
  a description after the trigger's name. Icon-only buttons still need an
  `aria-label`. Touch users never see tooltips, so don't put essential
  information or interactive content in them; use a
  [Popover](/docs/components/popover) instead.
</Callout>

### When to use

* Tooltip — a brief label or hint for a control, especially icon-only buttons, abbreviations and truncated text.
* [Popover](/docs/components/popover) — interactive content, or anything users need to read on touch devices.
* Inline help text (a field `description`) — guidance that should always be visible.
* [Toast](/docs/components/toast) — feedback about something that just happened.

## Anatomy

```tsx
<TooltipTrigger>          {/* hover, focus and delay handling */}
  <Button />              {/* focusable trigger */}
  <Tooltip>               {/* role="tooltip", optional arrow */}
    Label
  </Tooltip>
</TooltipTrigger>
```

| Part             | Renders                         | Notes                                                                                                                       |
| ---------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `TooltipTrigger` | —                               | Opens the tooltip on hover (after `delay`) or keyboard focus (immediately). Defaults to a 400ms open and 100ms close delay. |
| `Tooltip`        | `<div role="tooltip">` (portal) | The positioned bubble. Carries `data-slot="tooltip"`.                                                                       |
| Arrow            | `OverlayArrow` › `<svg>`        | 8px arrow pointing at the trigger. Rendered unless `showArrow={false}`.                                                     |

## Examples

### Placement

`placement` accepts `top` (default), `bottom`, `left`, `right`, `start`, `end` and combinations like `top start`. The tooltip flips to the opposite side when there isn't room, and the arrow rotates with it.

Example `tooltip/placement`: source in https://desyne.dev/docs/components/tooltip.md

### Light variant

`variant="light"` renders a bordered card that matches popovers. Use it for two-line content, like a metric name and its definition. Tooltips are capped at `max-w-xs`; pass a `max-w-*` class for a narrower measure.

Example `tooltip/light`: source in https://desyne.dev/docs/components/tooltip.md

### Without arrow

`showArrow={false}` hides the arrow. Drop the `offset` to keep the tooltip close to dense toolbars.

Example `tooltip/no-arrow`: source in https://desyne.dev/docs/components/tooltip.md

### With keyboard shortcut

Tooltips are a natural place to advertise shortcuts. Put a [`Kbd`](/docs/components/kbd) in the content; the light variant keeps it legible.

Example `tooltip/with-kbd`: source in https://desyne.dev/docs/components/tooltip.md

### Delay

`delay` and `closeDelay` on `TooltipTrigger` set how long hover waits before opening and closing. Once one tooltip has opened, moving to a nearby trigger opens the next one immediately. Keyboard focus always opens without delay.

Example `tooltip/delay`: source in https://desyne.dev/docs/components/tooltip.md

### Focus only

`trigger="focus"` shows the tooltip for keyboard focus only, not on hover. Use it for hints that would be noisy under the mouse.

Example `tooltip/focus-trigger`: source in https://desyne.dev/docs/components/tooltip.md

### Controlled

`isOpen` and `onOpenChange` on `TooltipTrigger` let you open the tooltip from code, like confirming a copy action. `shouldCloseOnPress={false}` keeps it open while the trigger is pressed.

Example `tooltip/controlled`: source in https://desyne.dev/docs/components/tooltip.md

### Disabling tooltips

`isDisabled` on `TooltipTrigger` turns the tooltip off without touching the trigger. Here tooltips only appear while the navigation is collapsed to icons. Disabled buttons never show tooltips, since they don't receive hover or focus.

Example `tooltip/disabled`: source in https://desyne.dev/docs/components/tooltip.md

### Custom trigger

Wrap non-interactive elements in React Aria's `Focusable` so they can own a tooltip. The child needs `tabIndex={0}` and an ARIA role (`button`, `img`, `link` and similar), and must forward its ref.

Example `tooltip/custom-trigger`: source in https://desyne.dev/docs/components/tooltip.md

## Recipes

### Collapsed navigation

An icon rail with right-side tooltips that show each destination and its shortcut. `delay={0}` makes scanning the rail instant.

Example `tooltip/recipe-icon-rail`: source in https://desyne.dev/docs/components/tooltip.md

### Avatar stack

Overlapping [`Avatar`](/docs/components/avatar)s, each wrapped in `Focusable` with `role="img"` and a name, show who has access on hover or focus.

Example `tooltip/recipe-avatar-stack`: source in https://desyne.dev/docs/components/tooltip.md

### Metric definitions

KPI cards with an info button next to each label. The light variant holds the metric's name and a short definition.

Example `tooltip/recipe-metric-card`: source in https://desyne.dev/docs/components/tooltip.md

## Accessibility

* The tooltip has `role="tooltip"` and is linked to its trigger with `aria-describedby`, so screen readers read it after the trigger's name.
* It opens on hover after `delay`, and immediately when the trigger receives keyboard focus. It doesn't open for touch.
* It closes on <kbd>Esc</kbd>, when the pointer leaves (after `closeDelay`), when focus moves away, and when the trigger is pressed (unless `shouldCloseOnPress={false}`).
* Keep tooltip content short and non-interactive. Anything focusable inside a tooltip can't be reached.
* The trigger must be focusable. Wrap plain elements in `Focusable` with a `tabIndex` and a role.

### Keyboard

| Key            | Action                                 |
| -------------- | -------------------------------------- |
| <kbd>Tab</kbd> | Focusing the trigger opens the tooltip |
| <kbd>Esc</kbd> | Hides the tooltip                      |

## Styling

### Data attributes

On the `Tooltip`:

| Attribute             | Present when                                                          |
| --------------------- | --------------------------------------------------------------------- |
| `data-placement`      | Always: the resolved side, `"top"`, `"bottom"`, `"left"` or `"right"` |
| `data-entering`       | Opening animation is running                                          |
| `data-exiting`        | Closing animation is running                                          |
| `data-slot="tooltip"` | Always                                                                |

The enter animation fades, zooms and slides in from the trigger's side based on `data-placement`.

### Customizing

* `className` on `Tooltip` styles the bubble: it's `w-fit max-w-xs rounded-md px-2.5 py-1.5 text-xs` with `text-balance`. Pass `max-w-*` or padding classes to change it, or `flex items-center gap-2` to lay out rich content.
* The default variant uses `bg-foreground text-background`, so it inverts with the theme; `light` uses `bg-popover` with a border.
* The arrow's fill follows the variant. When overriding the background, hide the arrow or restyle it via `[&_svg]:fill-…`.
* `--trigger-anchor-point` is set on the tooltip, for a custom `transform-origin`.

### Render props

`className` and `children` accept a function of the tooltip's state:

```tsx
<Tooltip className={({ placement }) => (placement === "bottom" ? "mt-1" : "")}>
  Label
</Tooltip>
```

## API Reference

### TooltipTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;A focusable trigger followed by a Tooltip.&#x22; },
  delay: { type: &#x22;number&#x22;, default: &#x22;400&#x22;, description: &#x22;Milliseconds of hover before the tooltip opens.&#x22; },
  closeDelay: { type: &#x22;number&#x22;, default: &#x22;100&#x22;, description: &#x22;Milliseconds before the tooltip closes after the pointer leaves.&#x22; },
  trigger: { type: '&#x22;hover&#x22; | &#x22;focus&#x22;', default: '&#x22;hover&#x22;', description: '&#x22;focus&#x22; opens the tooltip for keyboard focus only.' },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the tooltip, independent of the trigger.&#x22; },
  shouldCloseOnPress: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Close the tooltip when the trigger is pressed.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the tooltip opens or closes.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`TooltipTrigger`](https://react-aria.adobe.com/Tooltip#api).

### Tooltip

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;light&#x22;', default: '&#x22;default&#x22;', description: &#x22;Dark inverted chip, or a light bordered card.&#x22; },
  showArrow: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Renders an arrow pointing at the trigger.&#x22; },
  placement: { type: &#x22;Placement&#x22;, default: '&#x22;top&#x22;', description: 'Preferred position, e.g. &#x22;right&#x22;, &#x22;top start&#x22;.' },
  offset: { type: &#x22;number&#x22;, default: &#x22;8&#x22;, description: &#x22;Distance from the trigger along the main axis, in px.&#x22; },
  crossOffset: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Shift along the cross axis, in px.&#x22; },
  containerPadding: { type: &#x22;number&#x22;, default: &#x22;12&#x22;, description: &#x22;Minimum space between the tooltip and the viewport edge.&#x22; },
  shouldFlip: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Flip to the opposite side when there isn't enough room.&#x22; },
  arrowBoundaryOffset: { type: &#x22;number&#x22;, description: &#x22;Minimum distance between the arrow and the tooltip's edge.&#x22; },
  triggerRef: { type: &#x22;RefObject<Element | null>&#x22;, description: &#x22;Element to position against, when used without TooltipTrigger.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state, when used without TooltipTrigger.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state, when used without TooltipTrigger.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the open state changes, when used without TooltipTrigger.&#x22; },
  className: { type: &#x22;string | ((state: TooltipRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: TooltipRenderProps) => ReactNode)&#x22;, description: &#x22;Tooltip content.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Tooltip`](https://react-aria.adobe.com/Tooltip#api).

## Related

* [Popover](/docs/components/popover) — interactive content anchored to a trigger.
* [Button](/docs/components/button) — icon-only buttons are the most common tooltip trigger.
* [Kbd](/docs/components/kbd) — show shortcuts inside tooltips.
* [Toggle Button](/docs/components/toggle-button) — label icon-only toggles with a tooltip.

---

# Menu

Source: https://desyne.dev/docs/components/menu

> A dropdown list of actions or options, opened from a button, a long press or a right click. Supports icons, shortcuts, sections, single and multiple selection, links, submenus and typeahead, with full keyboard navigation.

```tsx title="menu/demo.tsx"
"use client";

import {
  CreditCardIcon,
  LogOutIcon,
  SettingsIcon,
  UserIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  MenuContent,
  MenuItem,
  MenuSection,
  MenuSeparator,
  MenuShortcut,
  MenuTrigger,
} from "@/components/ui/menu";

export default function MenuDemo() {
  return (
    <MenuTrigger>
      <Button variant="outline">Open menu</Button>
      <MenuContent className="w-56">
        <MenuSection title="My account">
          <MenuItem textValue="Profile">
            <UserIcon /> Profile <MenuShortcut>⇧⌘P</MenuShortcut>
          </MenuItem>
          <MenuItem textValue="Billing">
            <CreditCardIcon /> Billing <MenuShortcut>⌘B</MenuShortcut>
          </MenuItem>
          <MenuItem textValue="Settings">
            <SettingsIcon /> Settings <MenuShortcut>⌘S</MenuShortcut>
          </MenuItem>
        </MenuSection>
        <MenuSeparator />
        <MenuItem textValue="Log out" variant="destructive">
          <LogOutIcon /> Log out
        </MenuItem>
      </MenuContent>
    </MenuTrigger>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/menu
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  MenuContent,
  MenuItem,
  MenuSection,
  MenuSeparator,
  MenuShortcut,
  MenuTrigger,
  SubmenuTrigger,
} from "@/components/ui/menu";
```

```tsx
<MenuTrigger>
  <Button variant="outline">Actions</Button>
  <MenuContent onAction={(key) => run(key)}>
    <MenuItem id="edit">Edit</MenuItem>
    <MenuItem id="duplicate">Duplicate</MenuItem>
    <MenuSeparator />
    <MenuItem id="delete" variant="destructive">
      Delete
    </MenuItem>
  </MenuContent>
</MenuTrigger>
```

`MenuTrigger` connects the first child (any pressable, usually a [`Button`](/docs/components/button)) to the `MenuContent` after it. Handle actions with `onAction` on `MenuContent`, which receives the item's `id`, or with `onAction` on each `MenuItem`.

<Callout title="Set textValue when children aren't plain text">
  Typeahead and the item's text for assistive tech come from `textValue`.
  `MenuItem` fills it in when its children are a plain string; as soon as you
  add an icon or a shortcut, pass `textValue` yourself.
</Callout>

### When to use

* Menu — a list of actions ("Rename", "Delete") or view options ("Sort by", "Show columns") that don't need to be visible all the time.
* [Select](/docs/components/select) — choosing a form value that's shown in the trigger and submitted.
* [Command Palette](/docs/components/command-palette) — a searchable list of every action in the app.
* [Toggle Button Group](/docs/components/toggle-button-group) — a few options that should stay visible.
* [Popover](/docs/components/popover) — anything that isn't a list, like a small form.

## Anatomy

```tsx
<MenuTrigger>
  <Button />                     {/* trigger */}
  <MenuContent>                  {/* popover + role="menu" */}
    <MenuSection title="…">      {/* optional group with a heading */}
      <MenuItem>                 {/* role="menuitem" */}
        <Icon />
        Label
        <MenuShortcut />         {/* keyboard hint */}
      </MenuItem>
    </MenuSection>
    <MenuSeparator />
    <SubmenuTrigger>
      <MenuItem />               {/* opens the submenu */}
      <MenuContent />            {/* nested menu */}
    </SubmenuTrigger>
  </MenuContent>
</MenuTrigger>
```

| Part             | Renders                         | Notes                                                                                                                                                             |
| ---------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MenuTrigger`    | —                               | Opens the menu on press (or long press / right click) and wires up the trigger. From React Aria.                                                                  |
| `MenuContent`    | `Popover` › `<div role="menu">` | The positioned popover (`min-w-44`) and the scrollable menu inside it.                                                                                            |
| `MenuItem`       | `<div role="menuitem">`         | An action. Becomes `menuitemradio` / `menuitemcheckbox` with selection, and an `<a>` with `href`. Adds a selection indicator and a submenu chevron automatically. |
| `MenuSection`    | `<section role="group">`        | Groups items under an optional `title`. Can have its own selection.                                                                                               |
| `MenuSeparator`  | `<hr>`                          | A 1px divider between items or sections.                                                                                                                          |
| `MenuShortcut`   | `<kbd>`                         | Right-aligned shortcut hint, linked to the item for assistive tech.                                                                                               |
| `SubmenuTrigger` | —                               | Wraps a `MenuItem` and the nested `MenuContent` it opens. From React Aria.                                                                                        |

## Examples

### Sections

`MenuSection` groups related items under a small uppercase `title`, and `MenuSeparator` divides groups. Icons in items are sized and muted automatically; `MenuShortcut` right-aligns a keyboard hint. The demo above shows all three.

```tsx title="menu/demo.tsx"
"use client";

import {
  CreditCardIcon,
  LogOutIcon,
  SettingsIcon,
  UserIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  MenuContent,
  MenuItem,
  MenuSection,
  MenuSeparator,
  MenuShortcut,
  MenuTrigger,
} from "@/components/ui/menu";

export default function MenuDemo() {
  return (
    <MenuTrigger>
      <Button variant="outline">Open menu</Button>
      <MenuContent className="w-56">
        <MenuSection title="My account">
          <MenuItem textValue="Profile">
            <UserIcon /> Profile <MenuShortcut>⇧⌘P</MenuShortcut>
          </MenuItem>
          <MenuItem textValue="Billing">
            <CreditCardIcon /> Billing <MenuShortcut>⌘B</MenuShortcut>
          </MenuItem>
          <MenuItem textValue="Settings">
            <SettingsIcon /> Settings <MenuShortcut>⌘S</MenuShortcut>
          </MenuItem>
        </MenuSection>
        <MenuSeparator />
        <MenuItem textValue="Log out" variant="destructive">
          <LogOutIcon /> Log out
        </MenuItem>
      </MenuContent>
    </MenuTrigger>
  );
}
```

### Single selection

`selectionMode="single"` on `MenuContent` turns items into radio options with a dot indicator. Add `disallowEmptySelection` for settings like "Sort by" that always have a value, and reflect the choice in the trigger.

Example `menu/single-selection`: source in https://desyne.dev/docs/components/menu.md

### Selection in sections

Each `MenuSection` can have its own `selectionMode`, `selectedKeys` and `onSelectionChange`, mixing checkbox and radio groups in one menu. Multiple-selection menus stay open when an item is clicked, so several options can be toggled at once.

Example `menu/selection`: source in https://desyne.dev/docs/components/menu.md

### Rich items

Use React Aria's `Text` with `slot="label"` and `slot="description"` for two-line items. The slots wire up `aria-labelledby` and `aria-describedby`, so the description is announced separately from the name.

Example `menu/rich-items`: source in https://desyne.dev/docs/components/menu.md

### Dynamic items

Pass `items` and a render function instead of static children. Each item needs an `id` (or `key`) property; `onAction` receives it.

Example `menu/dynamic`: source in https://desyne.dev/docs/components/menu.md

### Submenus

Wrap a `MenuItem` and a nested `MenuContent` in `SubmenuTrigger`. The item gets a chevron, opens on hover (after a 200ms `delay`), <kbd>→</kbd> or <kbd>Enter</kbd>, and closes with <kbd>←</kbd>.

Example `menu/submenu`: source in https://desyne.dev/docs/components/menu.md

### Links

Give an item an `href` and it renders as a link, with `target`, `rel` and `download` passed through. It works with client-side routers through React Aria's `RouterProvider`.

Example `menu/links`: source in https://desyne.dev/docs/components/menu.md

### Disabled items

`disabledKeys` on `MenuContent` (or `isDisabled` on a `MenuItem`) keeps an item visible but unfocusable. Explain why nearby when it isn't obvious.

Example `menu/disabled`: source in https://desyne.dev/docs/components/menu.md

### Placement

The menu opens `bottom start` by default and flips when there isn't room. Use `placement="bottom end"` for triggers on the right edge of a layout, like a row's "more" button.

Example `menu/placement`: source in https://desyne.dev/docs/components/menu.md

### Context menu

`trigger="contextMenu"` opens the menu at the pointer on right click, on long press for touch, and with <kbd>Shift</kbd>+<kbd>F10</kbd> on Windows. The trigger must be a focusable React Aria element, like a `Button`.

Example `menu/context-menu`: source in https://desyne.dev/docs/components/menu.md

## Recipes

### Account menu

A user button that opens upward, sized to the trigger with `popoverClassName="w-(--trigger-width)"`. A React Aria `Header` shows who's signed in, and a theme submenu uses single selection.

Example `menu/recipe-account`: source in https://desyne.dev/docs/components/menu.md

### Row actions

A "more" menu on each row. "Delete…" opens a controlled alert [`Dialog`](/docs/components/dialog) after the menu closes, and the other actions confirm with a [toast](/docs/components/toast). The ellipsis in the label signals that the action asks for more input.

Example `menu/recipe-row-actions`: source in https://desyne.dev/docs/components/menu.md

### Column visibility

A multiple-selection menu that shows and hides table columns. It stays open while toggling, and the table updates live.

Example `menu/recipe-column-visibility`: source in https://desyne.dev/docs/components/menu.md

## Accessibility

* The trigger gets `aria-haspopup="menu"` and `aria-expanded`; the menu is labelled by its trigger unless you pass `aria-label`.
* Opening with the keyboard focuses the first item (<kbd>↑</kbd> focuses the last). Focus returns to the trigger on close.
* Items are announced as `menuitem`, or `menuitemradio` / `menuitemcheckbox` with their checked state when the menu or section has a `selectionMode`.
* Section titles label their group. `MenuShortcut` is linked to its item so the shortcut is announced.
* Typeahead jumps to the next item that starts with the typed characters, using `textValue`.
* Context menus don't get `aria-haspopup`, since they don't open on activation.

### Keyboard

| Key                                                | Action                                                               |
| -------------------------------------------------- | -------------------------------------------------------------------- |
| <kbd>Space</kbd> / <kbd>Enter</kbd> / <kbd>↓</kbd> | Opens the menu and focuses the first item                            |
| <kbd>↑</kbd>                                       | Opens the menu and focuses the last item                             |
| <kbd>↓</kbd> / <kbd>↑</kbd>                        | Moves focus between items, wrapping at the ends                      |
| <kbd>Home</kbd> / <kbd>End</kbd>                   | Focuses the first / last item                                        |
| <kbd>Enter</kbd>                                   | Runs the focused item and closes the menu                            |
| <kbd>Space</kbd>                                   | Runs or toggles the focused item; multiple-selection menus stay open |
| <kbd>→</kbd> / <kbd>←</kbd>                        | Opens / closes a submenu (reversed in right-to-left locales)         |
| <kbd>Esc</kbd>                                     | Closes the menu (or the current submenu)                             |
| Any character                                      | Typeahead to a matching item                                         |

## Styling

### Data attributes

On each `MenuItem`:

| Attribute             | Present when                                                 |
| --------------------- | ------------------------------------------------------------ |
| `data-focused`        | The item has focus (keyboard or hover)                       |
| `data-focus-visible`  | The item has keyboard focus                                  |
| `data-hovered`        | Hovered with a mouse or pen                                  |
| `data-pressed`        | Being pressed                                                |
| `data-selected`       | The item is selected                                         |
| `data-selection-mode` | The menu or section has `"single"` or `"multiple"` selection |
| `data-disabled`       | The item is disabled                                         |
| `data-has-submenu`    | The item opens a submenu                                     |
| `data-open`           | The item's submenu is open                                   |
| `data-variant`        | `"default"` or `"destructive"`                               |

`MenuContent`'s menu has `data-empty` when there are no items; its popover has the [popover attributes](/docs/components/popover#data-attributes), including `data-trigger="MenuTrigger"` or `"SubmenuTrigger"`.

### Slots

| `data-slot`      | Element                   |
| ---------------- | ------------------------- |
| `menu`           | The `role="menu"` element |
| `menu-item`      | Items                     |
| `menu-section`   | Sections                  |
| `menu-separator` | Separators                |
| `menu-shortcut`  | Shortcut hints            |
| `popover`        | The surrounding popover   |

### Customizing

* `className` on `MenuContent` styles the menu itself (width, padding); `popoverClassName` styles the popover around it, e.g. `w-(--trigger-width)` to match the trigger.
* Icons inside items are `size-4` and `text-muted-foreground` unless they have their own `size-*` or `text-*` class. Destructive items color their icons too.
* The menu scrolls within the popover's available height.

### Render props

`MenuItem`'s `className` and `children` accept a function of its state:

```tsx
<MenuItem className={({ isFocused }) => (isFocused ? "bg-brand/10" : "")}>
  {({ isSelected }) => (isSelected ? "Pinned" : "Pin")}
</MenuItem>
```

## API Reference

### MenuTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;A pressable trigger followed by MenuContent.&#x22; },
  trigger: { type: '&#x22;press&#x22; | &#x22;longPress&#x22; | &#x22;contextMenu&#x22;', default: '&#x22;press&#x22;', description: &#x22;How the menu opens.&#x22; },
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the menu opens or closes.&#x22; },
}"
/>

### MenuContent

<TypeTable
  type="{
  placement: { type: &#x22;Placement&#x22;, default: '&#x22;bottom start&#x22;', description: 'Preferred position, e.g. &#x22;bottom end&#x22;. Submenus default to &#x22;end top&#x22;.' },
  popoverClassName: { type: &#x22;string&#x22;, description: &#x22;Classes for the popover around the menu.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when an item is activated.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static items and sections, or a render function.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;none&#x22;', description: &#x22;Turns items into radio or checkbox options.&#x22; },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Prevents deselecting the last selected item.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Items that can't be focused or activated.&#x22; },
  shouldCloseOnSelect: { type: &#x22;boolean&#x22;, description: &#x22;Override whether the menu closes when an item is selected.&#x22; },
  renderEmptyState: { type: &#x22;() => ReactNode&#x22;, description: &#x22;Content shown when there are no items.&#x22; },
  autoFocus: { type: 'boolean | &#x22;first&#x22; | &#x22;last&#x22;', description: &#x22;Where focus goes when the menu opens. Set automatically by MenuTrigger.&#x22; },
  shouldFocusWrap: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Wrap focus from the last item to the first and back.&#x22; },
  escapeKeyBehavior: { type: '&#x22;clearSelection&#x22; | &#x22;none&#x22;', default: '&#x22;clearSelection&#x22;', description: &#x22;Whether Esc clears the selection before closing.&#x22; },
  dependencies: { type: &#x22;any[]&#x22;, description: &#x22;Values that should re-render dynamic items when they change.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Defaults to being labelled by the trigger.&#x22; },
  className: { type: &#x22;string | ((state: MenuRenderProps) => string)&#x22;, description: &#x22;Classes for the menu element.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Menu`](https://react-aria.adobe.com/Menu#api).

### MenuItem

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;destructive&#x22;', default: '&#x22;default&#x22;', description: &#x22;destructive colors the text and icon red.&#x22; },
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key, passed to onAction and used for selection.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Text for typeahead and assistive tech. Filled in automatically for plain-string children.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when this item is activated.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this item.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Renders the item as a link.&#x22; },
  target: { type: &#x22;string&#x22;, description: &#x22;Link target, e.g. _blank.&#x22; },
  rel: { type: &#x22;string&#x22;, description: &#x22;Link relationship.&#x22; },
  download: { type: &#x22;boolean | string&#x22;, description: &#x22;Download the linked file.&#x22; },
  routerOptions: { type: &#x22;RouterOptions&#x22;, description: &#x22;Options passed to your RouterProvider's navigate function.&#x22; },
  shouldCloseOnSelect: { type: &#x22;boolean&#x22;, description: &#x22;Override whether the menu closes when this item is selected.&#x22; },
  value: { type: &#x22;T&#x22;, description: &#x22;The item object, when using dynamic collections.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name, when the content isn't descriptive.&#x22; },
  className: { type: &#x22;string | ((state: MenuItemRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: MenuItemRenderProps) => ReactNode)&#x22;, description: &#x22;Content, or a function of the render state.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`MenuItem`](https://react-aria.adobe.com/Menu#menuitem), including hover, focus and press handlers.

### MenuSection

<TypeTable
  type="{
  title: { type: &#x22;string&#x22;, description: &#x22;Heading shown above the group; also labels it for assistive tech.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;MenuItems, or a render function.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', description: &#x22;Selection for this section only.&#x22; },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection for this section.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when this section's selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, description: &#x22;Prevents deselecting the last selected item.&#x22; },
  shouldCloseOnSelect: { type: &#x22;boolean&#x22;, description: &#x22;Override whether selecting an item in this section closes the menu.&#x22; },
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key for the section.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there is no title.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the section.&#x22; },
}"
/>

### SubmenuTrigger

<TypeTable
  type="{
  children: { type: &#x22;ReactElement[]&#x22;, description: &#x22;A MenuItem followed by a MenuContent.&#x22; },
  delay: { type: &#x22;number&#x22;, default: &#x22;200&#x22;, description: &#x22;Milliseconds of hover before the submenu opens.&#x22; },
}"
/>

### MenuSeparator / MenuShortcut

`MenuSeparator` accepts every prop of React Aria's [`Separator`](https://react-aria.adobe.com/Menu#separators). `MenuShortcut` accepts every prop of React Aria's `Keyboard` (a `<kbd>`).

## Related

* [Command Palette](/docs/components/command-palette) — the same items, searchable in a modal.
* [Select](/docs/components/select) — pick a form value from a list.
* [Popover](/docs/components/popover) — the surface menus render in.
* [Button](/docs/components/button) — split buttons pair a button with a menu.

---

# Command Palette

Source: https://desyne.dev/docs/components/command-palette

> A keyboard-driven command menu in a modal, filtered as you type. Built on React Aria's Autocomplete and Menu, with sections, shortcuts, icons, links, disabled commands and a custom empty state; accent- and case-insensitive matching out of the box.

```tsx title="command-palette/demo.tsx"
"use client";

import {
  CalculatorIcon,
  CalendarIcon,
  CreditCardIcon,
  SettingsIcon,
  SmileIcon,
  UserIcon,
} from "lucide-react";
import { useEffect, useState } from "react";
import { Button } from "@/components/ui/button";
import {
  CommandItem,
  CommandPalette,
  CommandSection,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command-palette";
import { Kbd } from "@/components/ui/kbd";

export default function CommandPaletteDemo() {
  const [isOpen, setOpen] = useState(false);

  useEffect(() => {
    const onKeyDown = (e: KeyboardEvent) => {
      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        setOpen((open) => !open);
      }
    };
    window.addEventListener("keydown", onKeyDown);
    return () => window.removeEventListener("keydown", onKeyDown);
  }, []);

  return (
    <>
      <Button
        variant="outline"
        className="text-muted-foreground"
        onPress={() => setOpen(true)}
      >
        Search commands… <Kbd>⌘K</Kbd>
      </Button>
      <CommandPalette isOpen={isOpen} onOpenChange={setOpen}>
        <CommandSection title="Suggestions">
          <CommandItem textValue="Calendar">
            <CalendarIcon /> Calendar
          </CommandItem>
          <CommandItem textValue="Search emoji">
            <SmileIcon /> Search emoji
          </CommandItem>
          <CommandItem textValue="Calculator" isDisabled>
            <CalculatorIcon /> Calculator
          </CommandItem>
        </CommandSection>
        <CommandSeparator />
        <CommandSection title="Settings">
          <CommandItem textValue="Profile">
            <UserIcon /> Profile <CommandShortcut>⌘P</CommandShortcut>
          </CommandItem>
          <CommandItem textValue="Billing">
            <CreditCardIcon /> Billing <CommandShortcut>⌘B</CommandShortcut>
          </CommandItem>
          <CommandItem textValue="Settings">
            <SettingsIcon /> Settings <CommandShortcut>⌘S</CommandShortcut>
          </CommandItem>
        </CommandSection>
      </CommandPalette>
    </>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/command-palette
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  CommandItem,
  CommandPalette,
  CommandSection,
  CommandSeparator,
  CommandShortcut,
} from "@/components/ui/command-palette";
```

```tsx
const [isOpen, setOpen] = useState(false);

<CommandPalette
  isOpen={isOpen}
  onOpenChange={setOpen}
  onAction={(key) => run(key)}
>
  <CommandItem id="new-project">New project</CommandItem>
  <CommandItem id="invite">Invite teammate</CommandItem>
</CommandPalette>
```

Control the palette with `isOpen` and `onOpenChange`, and bind the <kbd>⌘</kbd>+<kbd>K</kbd> shortcut yourself with a `keydown` listener (see the demo's code).

The palette closes itself after a command runs: once `onAction` (or an item's own `onAction`) has been called, it calls `onOpenChange(false)`. Links (`href` items) close it too. Pass `closeOnAction={false}` to keep it open, for example for multi-step commands, and close it yourself with `setOpen(false)` when you're done.

### When to use

* Command Palette — a global, searchable list of actions and destinations, usually on <kbd>⌘</kbd>+<kbd>K</kbd>. Also good for any "pick one from many" step, like assigning a teammate.
* [Menu](/docs/components/menu) — a short, contextual list of actions attached to a button.
* [Combo Box](/docs/components/combobox) — a searchable form field that keeps a value.
* [Search Field](/docs/components/search-field) — searching content on the page rather than running commands.

## Anatomy

```tsx
<CommandPalette>                 {/* overlay + modal + dialog + search input + menu */}
  <CommandSection title="…">     {/* optional group with a heading */}
    <CommandItem>                {/* a command */}
      <Icon />
      Label
      <CommandShortcut />        {/* keyboard hint */}
    </CommandItem>
  </CommandSection>
  <CommandSeparator />
</CommandPalette>
```

| Part               | Renders                                              | Notes                                                                                                                                 |
| ------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `CommandPalette`   | `ModalOverlay` › `Modal` › `Dialog` › `Autocomplete` | Backdrop, a panel near the top of the screen (`pt-[15vh]`), a search input and a `role="menu"` list that scrolls after 320px.         |
| Search input       | `SearchField` › `<input type="search">`              | Auto-focused, with `aria-label="Search commands"` and a search icon.                                                                  |
| `CommandItem`      | `<div role="menuitem">`                              | A command. Same component as [`MenuItem`](/docs/components/menu#menuitem): `variant`, `href`, `isDisabled` and render props all work. |
| `CommandSection`   | `<section role="group">`                             | Groups items under an optional `title`. Hidden when none of its items match.                                                          |
| `CommandSeparator` | `<hr>`                                               | Divider between sections.                                                                                                             |
| `CommandShortcut`  | `<kbd>`                                              | Right-aligned shortcut hint. The palette doesn't bind it.                                                                             |
| Empty state        | `<div>`                                              | `emptyMessage`, shown when nothing matches.                                                                                           |

## Examples

### Dynamic items

Pass `items` and a render function instead of static children. Each item needs an `id`; `onAction` receives it. Only the items that match the query are rendered.

Example `command-palette/dynamic`: source in https://desyne.dev/docs/components/command-palette.md

### Rich items

Put React Aria's `Text` with `slot="label"` and `slot="description"` inside a `CommandItem` for two-line results. The description is announced separately, and filtering still uses `textValue`.

Example `command-palette/rich-items`: source in https://desyne.dev/docs/components/command-palette.md

### Search keywords

Filtering matches the query anywhere in an item's `textValue`, ignoring case and accents. Add synonyms to `textValue` so "dark" finds Appearance or "2fa" finds Security. The item's accessible name still comes from its visible content.

Example `command-palette/keywords`: source in https://desyne.dev/docs/components/command-palette.md

### Links

Give an item an `href` to navigate. Same-page anchors, external URLs with `target="_blank"`, and routes through React Aria's `RouterProvider` all work.

Example `command-palette/links`: source in https://desyne.dev/docs/components/command-palette.md

### Disabled commands

`disabledKeys` keeps commands visible but not selectable, and keyboard navigation skips them. Say why, for example with a hint on the item.

Example `command-palette/disabled`: source in https://desyne.dev/docs/components/command-palette.md

### Empty state

`emptyMessage` accepts any node. Use it to suggest what to try next. `placeholder` sets the input's hint, and `aria-label` names the dialog (it defaults to "Command palette").

Example `command-palette/empty-state`: source in https://desyne.dev/docs/components/command-palette.md

## Recipes

### App search

The classic <kbd>⌘</kbd>+<kbd>K</kbd> palette: a search-style trigger button with a [`Kbd`](/docs/components/kbd) hint, a global shortcut, recent items, actions with shortcuts and navigation. `className="max-w-xl"` widens the panel.

Example `command-palette/recipe-app-search`: source in https://desyne.dev/docs/components/command-palette.md

### Assign a teammate

A palette used as a picker: people with [`Avatar`](/docs/components/avatar)s, searchable by name or email through `textValue`, that sets the assignee on an issue card.

Example `command-palette/recipe-assign`: source in https://desyne.dev/docs/components/command-palette.md

### Theme switcher

A narrow palette (`max-w-sm`) that switches the theme, with a check on the current option.

Example `command-palette/recipe-theme`: source in https://desyne.dev/docs/components/command-palette.md

## Accessibility

* The palette is a modal dialog: focus is trapped, the page is hidden from screen readers, and focus returns to the previously focused element on close.
* Focus stays in the search input while <kbd>↑</kbd> / <kbd>↓</kbd> move a virtual focus through the results, so users can keep typing. The highlighted command is announced as it changes.
* Name the dialog with `aria-label` when it has a specific purpose ("Assign issue"); the default is "Command palette".
* Commands are `menuitem`s with their text from `textValue`; section titles label their groups.
* Shortcuts shown with `CommandShortcut` are hints only. Register the keys with your own handler.

### Keyboard

| Key                                       | Action                                                          |
| ----------------------------------------- | --------------------------------------------------------------- |
| Any character                             | Filters the commands                                            |
| <kbd>↓</kbd> / <kbd>↑</kbd>               | Moves the highlight through the results                         |
| <kbd>Home</kbd> / <kbd>End</kbd>          | Highlights the first / last result                              |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | Moves the highlight by a page                                   |
| <kbd>Enter</kbd>                          | Runs the highlighted command                                    |
| <kbd>Esc</kbd>                            | Clears the query, or closes the palette when the query is empty |

## Styling

### Data attributes

On each `CommandItem`, the same attributes as [`MenuItem`](/docs/components/menu#data-attributes): `data-focused` for the highlighted result, `data-disabled`, `data-hovered`, `data-pressed` and `data-variant`. The panel has `data-entering` / `data-exiting` during its fade and zoom.

### Slots

| `data-slot`                                                    | Element               |
| -------------------------------------------------------------- | --------------------- |
| `command-palette-overlay`                                      | Backdrop              |
| `command-palette`                                              | Panel                 |
| `menu-item`, `menu-section`, `menu-separator`, `menu-shortcut` | Items and their parts |

### Customizing

* `className` styles the panel. It's `w-full max-w-lg` by default: use `max-w-xl` for a wider palette or `max-w-sm` for a focused picker.
* The result list is capped at `max-h-80` and scrolls; icons in items are sized and muted like in [Menu](/docs/components/menu#customizing).
* The backdrop reuses `overlayStyles` from [Dialog](/docs/components/dialog#customizing).

## API Reference

### CommandPalette

<TypeTable
  type="{
  isOpen: { type: &#x22;boolean&#x22;, description: &#x22;Controlled open state.&#x22; },
  defaultOpen: { type: &#x22;boolean&#x22;, description: &#x22;Uncontrolled initial open state.&#x22; },
  onOpenChange: { type: &#x22;(isOpen: boolean) => void&#x22;, description: &#x22;Called when the palette opens or closes.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when a command runs, with the item's id.&#x22; },
  closeOnAction: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Close the palette after a command's action fires. Set false to keep it open and close it yourself.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static CommandItems and CommandSections, or a render function.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Commands that can't be highlighted or run.&#x22; },
  placeholder: { type: &#x22;string&#x22;, default: '&#x22;Type a command or search…&#x22;', description: &#x22;Placeholder of the search input.&#x22; },
  emptyMessage: { type: &#x22;ReactNode&#x22;, default: '&#x22;No results found.&#x22;', description: &#x22;Shown when no command matches the query.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, default: '&#x22;Command palette&#x22;', description: &#x22;Accessible name of the dialog.&#x22; },
  isDismissable: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Close when clicking the backdrop.&#x22; },
  isKeyboardDismissDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Ignore the Esc key.&#x22; },
  shouldCloseOnInteractOutside: { type: &#x22;(element: Element) => boolean&#x22;, description: &#x22;Fine-grained control over which outside clicks close the palette.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the panel.&#x22; },
}"
/>

Also accepts the other props of React Aria's [`ModalOverlay`](https://react-aria.adobe.com/Modal#api). Filtering is provided by [`Autocomplete`](https://react-aria.adobe.com/Autocomplete).

### CommandItem / CommandSection / CommandSeparator / CommandShortcut

Re-exports of [`MenuItem`](/docs/components/menu#menuitem), [`MenuSection`](/docs/components/menu#menusection), `MenuSeparator` and `MenuShortcut`. They accept the same props; `CommandItem` also takes `textValue`, which is what the query is matched against.

## Related

* [Menu](/docs/components/menu) — the same items in a dropdown.
* [Dialog](/docs/components/dialog) — the modal the palette is built on.
* [Combo Box](/docs/components/combobox) — a searchable field that keeps a value.
* [Kbd](/docs/components/kbd) — show the shortcut that opens the palette.

---

# Tabs

Source: https://desyne.dev/docs/components/tabs

> Switch between related panels of content without leaving the page. Three styles (line, segmented, enclosed), two sizes, horizontal or vertical, with an animated selection indicator, keyboard navigation and support for tabs that are links.

```tsx title="tabs/demo.tsx"
"use client";

import { Tab, TabList, TabPanel, Tabs } from "@/components/ui/tabs";

const panels = [
  {
    id: "overview",
    title: "Overview",
    body: "Production is healthy. The last deployment finished 12 minutes ago with no errors.",
  },
  {
    id: "activity",
    title: "Activity",
    body: "148 deployments this month. A preview is created for every pull request.",
  },
  {
    id: "analytics",
    title: "Analytics",
    body: "32.4k visitors in the last 7 days, up 8% from the week before.",
  },
  {
    id: "settings",
    title: "Settings",
    body: "Manage domains, environment variables and build settings.",
  },
];

export default function TabsDemo() {
  return (
    <Tabs className="w-full max-w-md">
      <TabList aria-label="Project">
        {panels.map((p) => (
          <Tab key={p.id} id={p.id}>
            {p.title}
          </Tab>
        ))}
      </TabList>
      {panels.map((p) => (
        <TabPanel key={p.id} id={p.id} className="text-muted-foreground">
          {p.body}
        </TabPanel>
      ))}
    </Tabs>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/tabs
```

npm dependencies (installed by the CLI): react-aria-components, tailwind-variants.

## Usage

```tsx
import { Tab, TabList, TabPanel, Tabs } from "@/components/ui/tabs";
```

```tsx
<Tabs>
  <TabList aria-label="Account">
    <Tab id="profile">Profile</Tab>
    <Tab id="billing">Billing</Tab>
  </TabList>
  <TabPanel id="profile">…</TabPanel>
  <TabPanel id="billing">…</TabPanel>
</Tabs>
```

Each `Tab` is matched to the `TabPanel` with the same `id`. Only the selected panel is mounted. The first tab is selected by default; use `defaultSelectedKey` or `selectedKey` to change that.

<Callout title="Label the tab list">
  `TabList` renders `role="tablist"` and needs an accessible name. Pass
  `aria-label`, or `aria-labelledby` pointing at a visible heading.
</Callout>

### When to use

* Tabs — switch between peer views of the same object (a project's overview, deployments and settings) where only one view is needed at a time.
* [Toggle Button Group](/docs/components/toggle-button-group) — pick a value or mode that changes content in place without panels, such as a chart's metric. Segmented tabs look similar; use tabs only when each option has its own panel.
* [Disclosure](/docs/components/disclosure) — sections that users may want open at the same time, or content that should stay in reading order.
* [Sidebar](/docs/components/sidebar) or [Link](/docs/components/link)s — primary navigation between pages. Tabs can be links (see [Tabs as links](#tabs-as-links)), but keep them to a small set of sibling routes.

## Anatomy

```tsx
<Tabs>                    {/* state, orientation, variant and size */}
  <TabList>               {/* role="tablist" */}
    <Tab>                 {/* role="tab", or a link when href is set */}
      <Icon />            {/* optional, auto-sized */}
      Label
      <Badge />           {/* optional count or status */}
    </Tab>
  </TabList>
  <TabPanel />            {/* role="tabpanel", one per tab */}
</Tabs>
```

| Part                | Renders                     | Notes                                                                                                                                    |
| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `Tabs`              | `<div>`                     | Root. Holds selection state and passes `variant` and `size` to its parts through context. A column when horizontal, a row when vertical. |
| `TabList`           | `<div role="tablist">`      | The row (or column) of tabs. One tab stop; arrow keys move between tabs.                                                                 |
| `Tab`               | `<div role="tab">` or `<a>` | A tab. Needs an `id` that matches a panel. Renders a link when given `href`.                                                             |
| Selection indicator | `SelectionIndicator`        | Rendered inside every tab. Only the selected tab's indicator shows; it slides between tabs. Hidden for `enclosed`.                       |
| `TabPanel`          | `<div role="tabpanel">`     | Content for the tab with the same `id`. Labelled by its tab.                                                                             |

## Examples

### Segmented

A pill-shaped track with a raised thumb. Suits short, mutually exclusive views such as billing periods or chart ranges, and fits inside toolbars and card headers.

Example `tabs/segmented`: source in https://desyne.dev/docs/components/tabs.md

### Enclosed

Folder-style tabs that join the panel below. Give the panel a border without a top edge (`border border-t-0`) and remove the root gap (`gap-0`) so they connect. Good for editors and code samples.

Example `tabs/enclosed`: source in https://desyne.dev/docs/components/tabs.md

### Sizes

`md` (default) and `sm` for every variant. Use `sm` in dense surfaces like card headers, toolbars and side panels.

Example `tabs/sizes`: source in https://desyne.dev/docs/components/tabs.md

### With icons

Put a Lucide icon before the label. Icons are sized to 16px automatically unless you set a `size-*` class.

Example `tabs/icons`: source in https://desyne.dev/docs/components/tabs.md

### Icon only

Tabs without visible text need an `aria-label` on each `Tab`. A small segmented list works well as a view switcher.

Example `tabs/icon-only`: source in https://desyne.dev/docs/components/tabs.md

### With badges

Counts and statuses are plain children. Use a small [`Badge`](/docs/components/badge) so the tab height doesn't change.

Example `tabs/badges`: source in https://desyne.dev/docs/components/tabs.md

### Scrollable

Tabs don't wrap or shrink. A horizontal `TabList` watches its size, and when the tabs are wider than the space it has (many tabs, long labels, small screens) it gets `data-overflowing` and scrolls horizontally, with no vertical scrollbar and the indicator kept inside the scroll area. The selected tab is scrolled into view on mount and whenever the selection changes; tabs reached with the arrow keys scroll into view as they get focus. Pass `hideScrollbar` to hide the (thin) scrollbar; the list still scrolls with touch, a trackpad, <kbd>Shift</kbd>+wheel and the arrow keys.

The list is capped at its container's width (`max-w-full`, `min-w-0`), so this also works when the `TabList` sits in a flex row next to other controls. Lists that fit are left as they are.

Example `tabs/scrollable`: source in https://desyne.dev/docs/components/tabs.md

### Vertical

`orientation="vertical"` stacks the tabs beside the panel, and adds up and down arrow navigation. Give the `TabList` a fixed width. Useful for settings pages with many sections.

Example `tabs/vertical`: source in https://desyne.dev/docs/components/tabs.md

### Disabled

Disable individual tabs with `disabledKeys` on `Tabs` or `isDisabled` on a `Tab`, or every tab with `isDisabled` on `Tabs`. Disabled tabs are skipped by the keyboard. Tell users why a tab is unavailable, for example with an icon or a note in the page.

Example `tabs/disabled`: source in https://desyne.dev/docs/components/tabs.md

### Controlled

Own the selection with `selectedKey` and `onSelectionChange` when something outside the tabs needs to change it, such as Back and Continue buttons in a multi-step flow.

Example `tabs/controlled`: source in https://desyne.dev/docs/components/tabs.md

### Manual activation

By default, moving focus with the arrow keys selects the tab immediately. With `keyboardActivation="manual"`, arrows only move focus and <kbd>Enter</kbd> or <kbd>Space</kbd> selects. Use this when rendering a panel is expensive, for example when it fetches data.

Example `tabs/manual-activation`: source in https://desyne.dev/docs/components/tabs.md

### Dynamic tabs

Pass `items` to `TabList` with a render function, and map the same array to panels. Here a controlled `selectedKey` jumps to each new tab as it's added.

Example `tabs/dynamic`: source in https://desyne.dev/docs/components/tabs.md

### Tabs as links

Give each `Tab` an `href` to make it a real link (middle-click and "open in new tab" work). Selection then follows the URL: derive `selectedKey` from the current path, and wrap your app in React Aria's `RouterProvider` so clicks go through your client-side router. The preview uses a local stand-in for the router.

Example `tabs/links`: source in https://desyne.dev/docs/components/tabs.md

With the Next.js App Router:

```tsx title="app/providers.tsx"
"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}
```

```tsx title="app/team/tabs.tsx"
"use client";

import { usePathname } from "next/navigation";
import { Tab, TabList, Tabs } from "@/components/ui/tabs";

export function TeamTabs() {
  const pathname = usePathname();
  return (
    <Tabs selectedKey={pathname}>
      <TabList aria-label="Team">
        <Tab id="/team" href="/team">Overview</Tab>
        <Tab id="/team/activity" href="/team/activity">Activity</Tab>
        <Tab id="/team/members" href="/team/members">Members</Tab>
      </TabList>
    </Tabs>
  );
}
```

When the panels are separate routes, render only the `TabList` and let each page render its own content.

## Recipes

### Account settings

Line tabs as the header of a [`Card`](/docs/components/card), with a form in each panel and shared actions in the footer. Pad the `TabList` with the card's `px-(--card-px)` so the tabs line up with the content.

Example `tabs/recipe-account-settings`: source in https://desyne.dev/docs/components/tabs.md

### Install command

Small segmented tabs switch the package manager, with a copy button in the same bar. The `TabList` can sit inside any layout wrapper as long as it's within `Tabs`.

Example `tabs/recipe-install`: source in https://desyne.dev/docs/components/tabs.md

### Card with date range

A segmented range picker in `CardAction` drives the chart below. Wrapping the header and content in `Tabs` keeps the list and panels connected.

Example `tabs/recipe-analytics`: source in https://desyne.dev/docs/components/tabs.md

## Accessibility

* Implements the WAI-ARIA tabs pattern: `role="tablist"`, `role="tab"` with `aria-selected`, and `role="tabpanel"` labelled by its tab through `aria-labelledby`.
* The tab list is a single tab stop. Focus lands on the selected tab; the arrow keys move between tabs and wrap from the last to the first.
* A panel is focusable (`tabIndex="0"`) when it has no focusable content of its own, so keyboard users can reach and scroll it.
* Disabled tabs are skipped by keyboard navigation.
* Left and right arrows follow the reading direction and flip in right-to-left locales.
* The selection indicator animation is disabled when the user prefers reduced motion.
* Icon-only tabs need `aria-label`.

### Keyboard

| Key                                 | Action                                                       |
| ----------------------------------- | ------------------------------------------------------------ |
| <kbd>Tab</kbd>                      | Moves focus to the selected tab, then into the panel         |
| <kbd>←</kbd> / <kbd>→</kbd>         | Moves to the previous / next tab (both orientations)         |
| <kbd>↑</kbd> / <kbd>↓</kbd>         | Moves to the previous / next tab (vertical only)             |
| <kbd>Home</kbd> / <kbd>End</kbd>    | Moves to the first / last tab                                |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | Selects the focused tab (with `keyboardActivation="manual"`) |

## Styling

### Data attributes

On `Tabs` and `TabList`:

| Attribute          | Present when                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-orientation` | Always, set to `horizontal` or `vertical`. `Tabs` adds `group/tabs`, so children can use `group-data-[orientation=vertical]/tabs:…`. |

On `TabList` only:

| Attribute          | Present when                                        |
| ------------------ | --------------------------------------------------- |
| `data-overflowing` | A horizontal list is wider than its box and scrolls |

On each `Tab`:

| Attribute                             | Present when                        |
| ------------------------------------- | ----------------------------------- |
| `data-selected`                       | The tab is selected                 |
| `data-hovered`                        | Hovered with a mouse or pen         |
| `data-pressed`                        | Being pressed                       |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard |
| `data-disabled`                       | The tab is disabled                 |

On each `TabPanel`:

| Attribute                             | Present when                                     |
| ------------------------------------- | ------------------------------------------------ |
| `data-focused` / `data-focus-visible` | The panel has focus / keyboard focus             |
| `data-inert`                          | Mounted with `shouldForceMount` but not selected |
| `data-entering` / `data-exiting`      | The panel is animating in / out                  |

### Slots

| `data-slot` | Element    |
| ----------- | ---------- |
| `tabs`      | Root       |
| `tab-list`  | Tab list   |
| `tab`       | Each tab   |
| `tab-panel` | Each panel |

### Customizing

* `className` on every part accepts a string or a function of its render props, and is merged with the built-in classes with `tailwind-merge`.
* The tab label is wrapped in an inline `<span>` above the indicator, so icons and badges line up with the text.
* The `line` indicator and selected text use the `brand` color; the `segmented` thumb uses `card`. Override with classes such as `data-selected:text-foreground` on `Tab`.
* The root has `gap-4` between the list and the panels. Change it with `className="gap-0"` (as in the enclosed examples) or any other gap.

## API Reference

### Tabs

<TypeTable
  type="{
  variant: { type: '&#x22;line&#x22; | &#x22;segmented&#x22; | &#x22;enclosed&#x22;', default: '&#x22;line&#x22;', description: &#x22;Visual style, shared with every tab and list inside.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Text size, and tab height for segmented and enclosed.&#x22; },
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Direction of the tab list and of arrow-key navigation.&#x22; },
  selectedKey: { type: &#x22;Key | null&#x22;, description: &#x22;The selected tab (controlled).&#x22; },
  defaultSelectedKey: { type: &#x22;Key&#x22;, description: &#x22;The initially selected tab (uncontrolled). Defaults to the first enabled tab.&#x22; },
  onSelectionChange: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when the selected tab changes.&#x22; },
  keyboardActivation: { type: '&#x22;automatic&#x22; | &#x22;manual&#x22;', default: '&#x22;automatic&#x22;', description: &#x22;Whether arrow keys select tabs immediately, or only move focus.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Tabs that can't be selected or focused.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables every tab.&#x22; },
  className: { type: &#x22;string | ((state: TabsRenderProps) => string)&#x22;, description: &#x22;Classes for the root.&#x22; },
  children: { type: &#x22;ReactNode | ((state: TabsRenderProps) => ReactNode)&#x22;, description: &#x22;A TabList and TabPanels, in any layout.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Tabs`](https://react-aria.adobe.com/Tabs#api).

### TabList

<TypeTable
  type="{
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name for the tab list. Required unless aria-labelledby is set.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of a visible element that labels the tab list.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Tabs, or a render function.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that, when changed, re-render every item of a dynamic collection.&#x22; },
  hideScrollbar: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Hide the scrollbar when a horizontal list overflows. It still scrolls.&#x22; },
  className: { type: &#x22;string | ((state: TabListRenderProps) => string)&#x22; },
}"
/>

### Tab

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Must match the id of a TabPanel.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this tab.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Turns the tab into a link. Navigation goes through RouterProvider when present.&#x22; },
  target: { type: &#x22;string&#x22;, description: &#x22;Link target, when href is set.&#x22; },
  routerOptions: { type: &#x22;RouterOptions&#x22;, description: &#x22;Options passed to your router's navigate function.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required for icon-only tabs.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when the tab is pressed.&#x22; },
  className: { type: &#x22;string | ((state: TabRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: TabRenderProps) => ReactNode)&#x22;, description: &#x22;Label, icon and badges, or a function of the tab's state.&#x22; },
}"
/>

### TabPanel

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Matches the id of a Tab.&#x22; },
  shouldForceMount: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Keep the panel mounted when not selected. Inactive panels are inert and get data-inert; hide them yourself.&#x22; },
  className: { type: &#x22;string | ((state: TabPanelRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: TabPanelRenderProps) => ReactNode)&#x22; },
}"
/>

## Related

* [Toggle Button Group](/docs/components/toggle-button-group) — segmented control for a value, without panels.
* [Disclosure](/docs/components/disclosure) — sections that expand in place, several at once.
* [Sidebar](/docs/components/sidebar) — primary navigation for an app.
* [Card](/docs/components/card) — a common container for tabbed content.

---

# Breadcrumbs

Source: https://desyne.dev/docs/components/breadcrumbs

> Show where the current page sits in a hierarchy, with a link back to each level. Chevron, slash or dot separators, two sizes, icons, dynamic items and onAction for in-app navigation. The last item is marked as the current page automatically.

```tsx title="breadcrumbs/demo.tsx"
"use client";

import { Breadcrumb, Breadcrumbs } from "@/components/ui/breadcrumbs";

export default function BreadcrumbsDemo() {
  return (
    <Breadcrumbs>
      <Breadcrumb href="#">Home</Breadcrumb>
      <Breadcrumb href="#">Projects</Breadcrumb>
      <Breadcrumb href="#">acme-web</Breadcrumb>
      <Breadcrumb>Settings</Breadcrumb>
    </Breadcrumbs>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/breadcrumbs
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { Breadcrumb, Breadcrumbs } from "@/components/ui/breadcrumbs";
```

```tsx
<Breadcrumbs>
  <Breadcrumb href="/">Home</Breadcrumb>
  <Breadcrumb href="/projects">Projects</Breadcrumb>
  <Breadcrumb>Settings</Breadcrumb>
</Breadcrumbs>
```

The last `Breadcrumb` is the current page. It gets `aria-current="page"`, is rendered as non-interactive text even if it has an `href`, and has no separator after it.

### When to use

* Breadcrumbs — secondary navigation that shows the path to the current page in a hierarchy two or more levels deep: file systems, product catalogs, settings, docs.
* [Tabs](/docs/components/tabs) — sibling views at the same level, not a path.
* [Link](/docs/components/link) — a single "Back to…" link is often enough for shallow hierarchies and small screens.
* [Sidebar](/docs/components/sidebar) — primary navigation. Breadcrumbs complement it; they don't replace it.

## Anatomy

```tsx
<Breadcrumbs>                 {/* <ol> */}
  <Breadcrumb href="…" icon>  {/* <li> › link + separator */}
    Label
  </Breadcrumb>
  <Breadcrumb>                {/* current page: no link, no separator */}
    Label
  </Breadcrumb>
</Breadcrumbs>
```

| Part          | Renders                        | Notes                                                                                                                                       |
| ------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Breadcrumbs` | `<ol>`                         | Labelled "Breadcrumbs" by default (localized). Sets the separator style and text size for its items. Wraps onto multiple lines when needed. |
| `Breadcrumb`  | `<li>`                         | One level. Contains a React Aria `Link` with the optional `icon` and the label, or the children as-is with `link={false}`.                  |
| Link          | `<a>`, or `<span role="link">` | An `<a>` when `href` is set; a `<span>` for the current item, disabled items and items without `href`.                                      |
| Separator     | `<svg>` or `<span>`            | Chevron, slash or dot after every item except the current one. `aria-hidden`.                                                               |

## Examples

### Separators

`chevron` (default) suits app UIs, `slash` suits repository and workspace paths, and `dot` is a quieter option for marketing pages and metadata.

Example `breadcrumbs/separators`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Sizes

`md` (14px, default) above page titles, `sm` (12px) in dense headers, toolbars and cards.

Example `breadcrumbs/sizes`: source in https://desyne.dev/docs/components/breadcrumbs.md

### With icons

Pass `icon` to show an icon before the label. Icons inside the link are sized to 14px.

Example `breadcrumbs/icons`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Icon-only home

Keep the first level compact with an icon, and put the label in an `sr-only` span so the link still has an accessible name.

Example `breadcrumbs/icon-home`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Long labels

Wrap a label in a `<span>` with `max-w-*` and `truncate` to cap its width, and repeat the full text in `title` so it's available on hover. The full text stays in the accessibility tree.

Example `breadcrumbs/truncation`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Dynamic items

Pass `items` and a render function instead of static children. Each item needs a unique `id`.

Example `breadcrumbs/dynamic`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Handling actions

Without `href`, items render as link-role `<span>`s and pressing one calls `onAction` on `Breadcrumbs` with the item's `id`. Use this for in-app navigation that isn't URL based, like a folder picker.

Example `breadcrumbs/on-action`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Disabled

`isDisabled` on `Breadcrumbs` makes every item non-interactive. The links are dimmed to 50% opacity with a not-allowed cursor; the current item keeps its normal style.

Example `breadcrumbs/disabled`: source in https://desyne.dev/docs/components/breadcrumbs.md

### With a router

Breadcrumb links are React Aria `Link`s, so they go through your router when the app is wrapped in React Aria's `RouterProvider`. With the Next.js App Router:

```tsx title="app/providers.tsx"
"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}
```

```tsx
<Breadcrumbs>
  <Breadcrumb href="/settings">Settings</Breadcrumb>
  <Breadcrumb href="/settings/team">Team</Breadcrumb>
  <Breadcrumb>Roles</Breadcrumb>
</Breadcrumbs>
```

## Recipes

### Page header

Small breadcrumbs above the page title, with a status [`Badge`](/docs/components/badge) and actions on the right.

Example `breadcrumbs/recipe-page-header`: source in https://desyne.dev/docs/components/breadcrumbs.md

### Collapsed path

For deep hierarchies, keep the first and last levels and move the middle ones into a [`Menu`](/docs/components/menu). The collapsed level is a `Breadcrumb` with `link={false}`, which renders its children (here a menu trigger) as-is instead of wrapping them in a link, and still gets a separator.

Example `breadcrumbs/recipe-collapsed`: source in https://desyne.dev/docs/components/breadcrumbs.md

### App header

A workspace path in an app's top bar: an [`Avatar`](/docs/components/avatar) as the first icon, a plan badge inside a crumb, and a slash separator. The breadcrumbs are wrapped in a `<nav>` landmark.

Example `breadcrumbs/recipe-app-header`: source in https://desyne.dev/docs/components/breadcrumbs.md

## Accessibility

* Renders an ordered list (`<ol>`) labelled "Breadcrumbs" by default. Pass `aria-label` to change it, and wrap the list in a `<nav>` element when it's the page's breadcrumb trail so it's exposed as a navigation landmark.
* The last item has `aria-current="page"` and isn't focusable or interactive.
* Separators are `aria-hidden`, so screen readers announce only the labels.
* Items with an `href` are native links: middle-click, "open in new tab" and the browser's link preview work.
* Give icon-only items a text label with `sr-only`. `aria-label` on `Breadcrumb` is applied to the `<li>`, not the link.

### Keyboard

| Key                                              | Action                                                       |
| ------------------------------------------------ | ------------------------------------------------------------ |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between breadcrumb links (the current item is skipped) |
| <kbd>Enter</kbd>                                 | Follows the focused link, or calls `onAction`                |

## Styling

### Data attributes

On each `Breadcrumb` (`<li>`) and its link:

| Attribute       | Present when                                                   |
| --------------- | -------------------------------------------------------------- |
| `data-current`  | It's the last item (the current page)                          |
| `data-disabled` | It's the current item, or `isDisabled` is set on `Breadcrumbs` |

On the link only:

| Attribute                             | Present when                        |
| ------------------------------------- | ----------------------------------- |
| `data-hovered` / `data-pressed`       | Hovered / being pressed             |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard |

The current item's link is `font-medium text-foreground`; the others are `text-muted-foreground` and turn `text-foreground` on hover. Disabled links (other than the current item) get `opacity-50` and `cursor-not-allowed`.

### Slots

| `data-slot`   | Element     |
| ------------- | ----------- |
| `breadcrumbs` | `<ol>` root |
| `breadcrumb`  | Each `<li>` |

### Customizing

* `className` on `Breadcrumbs` styles the list (a wrapping flex row with `gap-1.5`). It must be a string.
* `className` on `Breadcrumb` styles the `<li>`, and accepts a function of `{ isCurrent, isDisabled }`.
* To restyle the links, target them from the list, e.g. `className="[&_a]:underline"`.
* With `link={false}`, the children aren't wrapped or styled, and `isDisabled` on `Breadcrumbs` doesn't reach them. Disable a menu trigger inside yourself.

## API Reference

### Breadcrumbs

<TypeTable
  type="{
  separator: { type: '&#x22;chevron&#x22; | &#x22;slash&#x22; | &#x22;dot&#x22;', default: '&#x22;chevron&#x22;', description: &#x22;Separator shown after every item except the current one.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Text size: 12px or 14px.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Breadcrumb elements, or a render function.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called with the item's id when a breadcrumb is pressed.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Makes every breadcrumb link non-interactive and dims it. Doesn't affect link={false} content.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that, when changed, re-render every item of a dynamic collection.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, default: '&#x22;Breadcrumbs&#x22;', description: &#x22;Accessible name of the list.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the <ol>.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Breadcrumbs`](https://react-aria.adobe.com/Breadcrumbs#api).

### Breadcrumb

<TypeTable
  type="{
  href: { type: &#x22;string&#x22;, description: &#x22;Link target. Ignored for the current item.&#x22; },
  icon: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon or avatar shown before the label, inside the link.&#x22; },
  link: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Wrap the children in a React Aria Link. false renders them as-is (e.g. a menu trigger), keeping the separator.&#x22; },
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Passed to onAction, and required with dynamic items.&#x22; },
  children: { type: &#x22;ReactNode | ((state: BreadcrumbRenderProps) => ReactNode)&#x22;, description: &#x22;The label, or a function of { isCurrent, isDisabled }.&#x22; },
  className: { type: &#x22;string | ((state: BreadcrumbRenderProps) => string)&#x22;, description: &#x22;Classes for the <li>.&#x22; },
}"
/>

## Related

* [Link](/docs/components/link) — the link used inside each breadcrumb.
* [Sidebar](/docs/components/sidebar) — primary navigation, often paired with breadcrumbs in the content header.
* [Menu](/docs/components/menu) — for collapsed levels in deep paths.
* [Tabs](/docs/components/tabs) — switching between sibling views.

---

# Link

Source: https://desyne.dev/docs/components/link

> Navigate to another page or resource. Three styles, an external mode that opens a new tab with an arrow, disabled and current states, and client-side routing through React Aria's RouterProvider.

```tsx title="link/demo.tsx"
"use client";

import { Link } from "@/components/ui/link";

export default function LinkDemo() {
  return (
    <p className="max-w-sm text-muted-foreground text-sm leading-relaxed">
      By continuing you agree to our <Link href="#">Terms of Service</Link> and{" "}
      <Link href="#">Privacy Policy</Link>.
    </p>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/link
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

```tsx
import { Link } from "@/components/ui/link";
```

```tsx
<Link href="/pricing">Pricing</Link>
```

### When to use

* Link — navigation: to another page, a section of this page, a file download or an email address.
* [Button](/docs/components/button) — an action that doesn't navigate (submit, open a dialog, delete). If it needs to look like a link, use `<Button variant="link">`.
* A button-styled link — navigation that should look like a button. Apply [`buttonVariants`](/docs/components/button#as-a-link) to a React Aria or Next.js link.
* [Breadcrumbs](/docs/components/breadcrumbs) and [Pagination](/docs/components/pagination) — structured navigation, built on the same link.

## Anatomy

```tsx
<Link href="…">   {/* <a>, or <span role="link"> without href */}
  <Icon />        {/* optional, size it yourself */}
  Label
  {/* ↗ arrow, added when isExternal */}
</Link>
```

| Part           | Renders                       | Notes                                                                                                                                     |
| -------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Link`         | `<a>` or `<span role="link">` | An `<a>` when `href` is set and the link isn't disabled; otherwise a focusable `<span>` with `role="link"`. Inline flex with a small gap. |
| External arrow | `<svg>`                       | Appended after the children when `isExternal`. `aria-hidden`.                                                                             |

## Examples

### Variants

`default` is the brand-colored, medium-weight link for calls to action and standalone links. `subtle` is muted until hovered, for footers, metadata and dense navigation. `underline` keeps the text color with a soft underline, for links inside body copy where color alone isn't enough.

Example `link/variants`: source in https://desyne.dev/docs/components/link.md

### External

`isExternal` sets `target="_blank"` and `rel="noreferrer"` and adds an arrow icon. Pass your own `target` or `rel` to override them.

Example `link/external`: source in https://desyne.dev/docs/components/link.md

### Disabled

`isDisabled` renders a `<span>` instead of an `<a>`, removes it from the tab order and dims it. Prefer hiding links that can never be followed; disable ones that will become available.

Example `link/disabled`: source in https://desyne.dev/docs/components/link.md

### With icon

Children are laid out in an inline flex row, so icons line up with the text. Icons aren't sized automatically; add `size-4` (or `size-3.5` for small text) and widen the gap with `gap-1.5`. `download` and `mailto:` links work as on a native `<a>`.

Example `link/with-icon`: source in https://desyne.dev/docs/components/link.md

### Current page

Set `aria-current="page"` on the link for the page you're on. React Aria exposes it as `data-current`, so you can style it with `data-current:…`.

Example `link/current`: source in https://desyne.dev/docs/components/link.md

### With a router

Wrap your app in React Aria's `RouterProvider` and every `Link` (plus breadcrumbs, tabs, menu items and other link-capable components) navigates with your client-side router. Modifier clicks, `target="_blank"` and cross-origin links still use the browser.

```tsx title="app/providers.tsx"
"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}
```

Pass router-specific options with `routerOptions`; they're forwarded as the second argument to `navigate`. Register their type once so they're type-checked:

```tsx title="app/providers.tsx"
declare module "react-aria-components" {
  interface RouterConfig {
    routerOptions: NonNullable<
      Parameters<ReturnType<typeof useRouter>["push"]>[1]
    >;
  }
}
```

```tsx
<Link href="/settings" routerOptions={{ scroll: false }}>
  Settings
</Link>
```

To use Next.js prefetching, style `next/link` with `linkVariants` instead. Hover and focus styles in `linkVariants` rely on React Aria's `data-hovered` and `data-focus-visible` attributes, so add `hover:` and `focus-visible:` classes when using it on a plain element.

## Recipes

### Site footer

Columns of `subtle` links grouped in labelled `<nav>` elements, with legal links and an external link in the bottom row.

Example `link/recipe-footer`: source in https://desyne.dev/docs/components/link.md

### Sign-in form

Inline links around a form: "Forgot password?" aligned under the field, a sign-up prompt, and `underline` links in the legal text.

Example `link/recipe-sign-in`: source in https://desyne.dev/docs/components/link.md

## Accessibility

* With `href`, renders a native `<a>`, so browser features like "open in new tab", copy link address and the status-bar preview work, and screen readers list it as a link.
* Without `href` (or when disabled), renders a `<span role="link">` that's focusable and responds to <kbd>Enter</kbd>. Prefer a [Button](/docs/components/button) for actions.
* `isDisabled` sets `aria-disabled` and removes the link from the tab order.
* The focus ring appears only for keyboard focus (`data-focus-visible`).
* The external arrow is `aria-hidden`. If opening a new tab could surprise users, say so in the text or add an `sr-only` "(opens in a new tab)".
* Don't rely on color alone to identify links in body text; use the `underline` variant there.

### Keyboard

| Key              | Action                  |
| ---------------- | ----------------------- |
| <kbd>Tab</kbd>   | Moves focus to the link |
| <kbd>Enter</kbd> | Follows the link        |

## Styling

### Data attributes

| Attribute                             | Present when                        |
| ------------------------------------- | ----------------------------------- |
| `data-hovered`                        | Hovered with a mouse or pen         |
| `data-pressed`                        | Being pressed                       |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard |
| `data-current`                        | `aria-current` is set               |
| `data-disabled`                       | `isDisabled` is true                |
| `data-slot="link"`                    | Always                              |

### Render props

`className` and `children` accept a function of the link's state:

```tsx
<Link href="/inbox" className={({ isCurrent }) => (isCurrent ? "font-semibold" : "")}>
  {({ isHovered }) => (isHovered ? "Open inbox →" : "Inbox")}
</Link>
```

### `linkVariants`

The `tailwind-variants` function behind the component.

```tsx
import { linkVariants } from "@/components/ui/link";

linkVariants({ variant: "subtle", className: "text-xs" });
```

## API Reference

### Link

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;subtle&#x22; | &#x22;underline&#x22;', default: '&#x22;default&#x22;', description: 'Visual style. &#x22;muted&#x22; is accepted as a legacy alias for &#x22;subtle&#x22;.' },
  href: { type: &#x22;string&#x22;, description: &#x22;The URL to link to. Without it, the link renders as a span.&#x22; },
  isExternal: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: 'Opens in a new tab (target=&#x22;_blank&#x22;, rel=&#x22;noreferrer&#x22;) and shows an arrow.' },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables the link and renders it as a span.&#x22; },
  target: { type: &#x22;string&#x22;, description: &#x22;Where to open the link. Overrides the value set by isExternal.&#x22; },
  rel: { type: &#x22;string&#x22;, description: &#x22;Relationship to the linked resource. Overrides the value set by isExternal.&#x22; },
  download: { type: &#x22;boolean | string&#x22;, description: &#x22;Downloads the URL, optionally with a suggested file name.&#x22; },
  hrefLang: { type: &#x22;string&#x22;, description: &#x22;Language of the linked page.&#x22; },
  ping: { type: &#x22;string&#x22;, description: &#x22;URLs to ping when the link is followed.&#x22; },
  referrerPolicy: { type: &#x22;HTMLAttributeReferrerPolicy&#x22;, description: &#x22;How much referrer information to send.&#x22; },
  routerOptions: { type: &#x22;RouterOptions&#x22;, description: &#x22;Options passed to your router's navigate function.&#x22; },
  &#x22;aria-current&#x22;: { type: 'boolean | &#x22;page&#x22; | &#x22;step&#x22; | &#x22;location&#x22; | &#x22;date&#x22; | &#x22;time&#x22; | &#x22;true&#x22; | &#x22;false&#x22;', description: &#x22;Marks the link as the current item. Exposed as data-current.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when the link is pressed.&#x22; },
  onHoverChange: { type: &#x22;(isHovering: boolean) => void&#x22;, description: &#x22;Called when the hover state changes.&#x22; },
  autoFocus: { type: &#x22;boolean&#x22;, description: &#x22;Focuses the link on mount.&#x22; },
  className: { type: &#x22;string | ((state: LinkRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
  children: { type: &#x22;ReactNode | ((state: LinkRenderProps) => ReactNode)&#x22;, description: &#x22;Content, or a function of the render state.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Link`](https://react-aria.adobe.com/Link#api).

### linkVariants

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;subtle&#x22; | &#x22;underline&#x22; | &#x22;muted&#x22;', default: '&#x22;default&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Button](/docs/components/button) — for actions, and `buttonVariants` for button-styled links.
* [Breadcrumbs](/docs/components/breadcrumbs) — a trail of links to parent pages.
* [Pagination](/docs/components/pagination) — links between pages of results.
* [Sidebar](/docs/components/sidebar) — navigation links for an app.

---

# Pagination

Source: https://desyne.dev/docs/components/pagination

> Move between pages of results. Use the ready-made Paginator for state-driven lists with automatic ellipses, a compact "Page x of y" mode and two sizes, or compose link-based pagination where every page has its own URL. Exports the getPageRange helper behind the ellipsis logic.

```tsx title="pagination/demo.tsx"
"use client";

import { useState } from "react";
import { Paginator } from "@/components/ui/pagination";

export default function PaginationDemo() {
  const [page, setPage] = useState(5);
  return <Paginator page={page} pageCount={20} onPageChange={setPage} />;
}
```

## Installation

```bash
npx shadcn@latest add @desyne/pagination
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { Paginator } from "@/components/ui/pagination";
```

```tsx
const [page, setPage] = useState(1);

<Paginator page={page} pageCount={20} onPageChange={setPage} />;
```

For link-based pagination, where each page has its own URL, compose the parts:

```tsx
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";
```

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=3" />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

### When to use

* `Paginator` — client-side state: tables, lists and search results where the page lives in React state and URLs don't need to change.
* Link-based parts — server-rendered or routed lists where each page should be linkable, bookmarkable and crawlable (`?page=3`).
* Simple mode — narrow spaces like card footers and mobile layouts, or very large page counts where numbers don't help.
* Consider infinite scrolling or a "Load more" [Button](/docs/components/button) for feeds, where users browse rather than look for a specific page.

## Anatomy

```tsx
<Pagination>                 {/* <nav aria-label="pagination"> */}
  <PaginationContent>        {/* <ul> */}
    <PaginationItem>         {/* <li> */}
      <PaginationPrevious />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink />     {/* page number */}
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis /> {/* skipped pages */}
    </PaginationItem>
    <PaginationItem>
      <PaginationNext />
    </PaginationItem>
  </PaginationContent>
</Pagination>

<Paginator />                {/* all of the above, with buttons, in one component */}
```

| Part                                    | Renders                         | Notes                                                                                                                                                |
| --------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Pagination`                            | `<nav aria-label="pagination">` | Landmark. Centered, full width by default.                                                                                                           |
| `PaginationContent`                     | `<ul>`                          | Row of items with `gap-1`.                                                                                                                           |
| `PaginationItem`                        | `<li>`                          | Wraps one link, button or ellipsis.                                                                                                                  |
| `PaginationLink`                        | React Aria `Link`               | A page link styled with `buttonVariants`: `ghost` normally, `outline` with a primary border when `isActive` (which also sets `aria-current="page"`). |
| `PaginationPrevious` / `PaginationNext` | `PaginationLink`                | Chevron plus "Previous" / "Next" text. The text is hidden below the `sm` breakpoint.                                                                 |
| `PaginationEllipsis`                    | `<span aria-hidden>`            | "…" icon for skipped pages.                                                                                                                          |
| `Paginator`                             | `Pagination` with buttons       | Previous and next icon buttons, page-number buttons from `getPageRange()`, or "Page x of y" in simple mode.                                          |

## Examples

### Sizes

`md` (32px, default) and `sm` (28px) for tables and dense toolbars.

Example `pagination/sizes`: source in https://desyne.dev/docs/components/pagination.md

### Simple

`simple` replaces the page numbers with "Page x of y" between the arrows. It takes a fixed amount of space regardless of the page count.

Example `pagination/simple`: source in https://desyne.dev/docs/components/pagination.md

### Siblings

`siblings` sets how many pages are shown on each side of the current page (default `1`). The first and last pages are always shown, and a gap becomes an ellipsis.

Example `pagination/siblings`: source in https://desyne.dev/docs/components/pagination.md

### Few pages

When every page fits (`pageCount` up to `siblings * 2 + 5`, so 7 by default), all numbers are shown with no ellipsis. Previous is disabled on the first page and Next on the last.

Example `pagination/few-pages`: source in https://desyne.dev/docs/components/pagination.md

### Link-based

Compose `PaginationLink`, `PaginationPrevious`, `PaginationNext` and `PaginationEllipsis` when each page is a URL. Mark the current page with `isActive`.

Example `pagination/links`: source in https://desyne.dev/docs/components/pagination.md

### Link sizes

Link parts accept `size="sm"` or `size="md"` (`"default"` and `"icon"` are accepted as aliases for `md`).

Example `pagination/links-sizes`: source in https://desyne.dev/docs/components/pagination.md

### With a router and getPageRange

Build the page list with `getPageRange(page, pageCount, siblings?)`, which returns numbers and `"ellipsis"` markers, and disable Previous and Next at the ends with `isDisabled`. Wrap the app in React Aria's `RouterProvider` so the links use client-side navigation. The preview uses a local stand-in for the router.

Example `pagination/links-router`: source in https://desyne.dev/docs/components/pagination.md

With the Next.js App Router, read the page from the URL:

```tsx title="app/invoices/page.tsx"
import { InvoicePagination } from "./invoice-pagination";

export default async function Page({ searchParams }: { searchParams: Promise<{ page?: string }> }) {
  const page = Number((await searchParams).page ?? 1);
  // …fetch the rows for `page`
  return <InvoicePagination page={page} pageCount={24} />;
}
```

`InvoicePagination` is a client component that renders the parts as in the preview, with an `href` of `?page=N` for each page. Your app's `RouterProvider` passes `router.push` as `navigate`.

```ts
getPageRange(5, 10); // [1, "ellipsis", 4, 5, 6, "ellipsis", 10]
getPageRange(2, 10); // [1, 2, 3, "ellipsis", 10]
getPageRange(2, 6); // [1, 2, 3, 4, 5, 6]
```

## Recipes

### Table footer

A rows-per-page [`Select`](/docs/components/select), a range summary and a small paginator under a [`Table`](/docs/components/table). Changing the page size resets to page 1. Pass `className="mx-0 w-auto"` to stop the paginator from centering itself.

Example `pagination/recipe-table`: source in https://desyne.dev/docs/components/pagination.md

### Card footer

A compact simple paginator aligned to the end of a [`Card`](/docs/components/card) footer with `className="justify-end"`.

Example `pagination/recipe-activity`: source in https://desyne.dev/docs/components/pagination.md

## Accessibility

* Rendered in a `<nav aria-label="pagination">` landmark. Pass your own `aria-label` (for example "Search results pages") when a page has more than one.
* The current page has `aria-current="page"`.
* `Paginator` labels its buttons "Previous page", "Next page" and "Page 3"; the link parts label Previous and Next "Go to previous page" and "Go to next page". Override any of them with `aria-label`.
* Previous and Next are disabled (and removed from the tab order) at the ends.
* Ellipses are `aria-hidden`.
* After changing pages in client-side lists, consider moving focus to the top of the results or announcing the change, so screen-reader users know the content updated.

### Keyboard

| Key                                              | Action                                                                  |
| ------------------------------------------------ | ----------------------------------------------------------------------- |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the controls                                              |
| <kbd>Enter</kbd>                                 | Activates the focused page, Previous or Next                            |
| <kbd>Space</kbd>                                 | Activates a `Paginator` button (links respond to <kbd>Enter</kbd> only) |

## Styling

### Data attributes

On `PaginationLink`, `PaginationPrevious`, `PaginationNext` and the `Paginator` buttons:

| Attribute                       | Present when                                     |
| ------------------------------- | ------------------------------------------------ |
| `data-hovered` / `data-pressed` | Hovered / being pressed                          |
| `data-focus-visible`            | Focused with the keyboard                        |
| `data-disabled`                 | Disabled                                         |
| `data-active`                   | Link parts with `isActive`                       |
| `data-current`                  | Link parts with `isActive` (from `aria-current`) |

### Slots

| `data-slot`           | Element        |
| --------------------- | -------------- |
| `pagination`          | `<nav>` root   |
| `pagination-content`  | `<ul>`         |
| `pagination-item`     | Each `<li>`    |
| `pagination-link`     | Each link part |
| `pagination-ellipsis` | Ellipsis       |

### Customizing

* Items use [`buttonVariants`](/docs/components/button#buttonvariants), so they follow button tones and radii. Page numbers are `tabular-nums` so widths don't shift.
* `className` on `Pagination` or `Paginator` styles the `<nav>`. It's centered with `mx-auto flex w-full justify-center`; use `justify-start`, `justify-end` or `mx-0 w-auto` to align it.
* `className` on `PaginationLink` must be a string.

## API Reference

### Paginator

<TypeTable
  type="{
  page: { type: &#x22;number&#x22;, description: &#x22;Current page, starting at 1.&#x22; },
  pageCount: { type: &#x22;number&#x22;, description: &#x22;Total number of pages.&#x22; },
  onPageChange: { type: &#x22;(page: number) => void&#x22;, description: &#x22;Called with the new page when a page, Previous or Next is pressed.&#x22; },
  siblings: { type: &#x22;number&#x22;, default: &#x22;1&#x22;, description: &#x22;Pages shown on each side of the current page.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Button size: 28px or 32px.&#x22; },
  simple: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: 'Shows &#x22;Page 3 of 10&#x22; instead of page numbers.' },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the <nav>.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, default: '&#x22;pagination&#x22;', description: &#x22;Accessible name of the navigation landmark.&#x22; },
}"
/>

Also accepts every prop of `<nav>` except `onChange`.

### PaginationLink

<TypeTable
  type="{
  href: { type: &#x22;string&#x22;, description: &#x22;URL of the page.&#x22; },
  isActive: { type: &#x22;boolean&#x22;, description: 'Marks the current page: outline style, aria-current=&#x22;page&#x22; and data-active.' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;default&#x22; | &#x22;icon&#x22;', default: '&#x22;md&#x22;', description: &#x22;sm is 28px; the others are 32px.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables the link and renders it as a span.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when the link is pressed.&#x22; },
  routerOptions: { type: &#x22;RouterOptions&#x22;, description: &#x22;Options passed to your router's navigate function.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with the button styles.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;The page number or custom content.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Link`](https://react-aria.adobe.com/Link#api) except a function `className`.

### PaginationPrevious / PaginationNext

Accept the same props as `PaginationLink`. Their content is fixed (chevron and label); `aria-label` defaults to "Go to previous page" / "Go to next page".

### Pagination / PaginationContent / PaginationItem / PaginationEllipsis

Accept every prop of `<nav>` / `<ul>` / `<li>` / `<span>`.

### getPageRange

<TypeTable
  type="{
  page: { type: &#x22;number&#x22;, description: &#x22;Current page, starting at 1.&#x22; },
  pageCount: { type: &#x22;number&#x22;, description: &#x22;Total number of pages.&#x22; },
  siblings: { type: &#x22;number&#x22;, default: &#x22;1&#x22;, description: &#x22;Pages on each side of the current page.&#x22; },
}"
/>

Returns `(number | "ellipsis")[]`: always the first and last page, the current page with its siblings, and `"ellipsis"` for each gap. When `pageCount` is at most `siblings * 2 + 5`, returns every page.

## Related

* [Table](/docs/components/table) — the most common place for pagination.
* [Select](/docs/components/select) — rows-per-page pickers.
* [Link](/docs/components/link) — the link used by the link-based parts.
* [Button](/docs/components/button) — `buttonVariants` styles every item.

---

# Disclosure

Source: https://desyne.dev/docs/components/disclosure

> Collapsible sections of content, on their own or grouped as an accordion. Three group styles (line, card, separated), chevron or plus indicators, single or multiple expansion, controlled state, and a height animation that respects reduced motion. Collapsed content stays findable with the browser's find-in-page.

```tsx title="disclosure/demo.tsx"
"use client";

import {
  Disclosure,
  DisclosureGroup,
  DisclosurePanel,
  DisclosureTrigger,
} from "@/components/ui/disclosure";

const faqs = [
  {
    id: "a11y",
    q: "Is it accessible?",
    a: "Yes. Every component is built on React Aria and follows WAI-ARIA patterns.",
  },
  {
    id: "shadcn",
    q: "Does it work with shadcn/ui?",
    a: "Yes. It uses the same tokens and installs with the shadcn CLI.",
  },
  {
    id: "themes",
    q: "Can I change the theme?",
    a: "Change the CSS variables. Every component reads from them.",
  },
];

export default function DisclosureDemo() {
  return (
    <DisclosureGroup className="max-w-md" defaultExpandedKeys={["a11y"]}>
      {faqs.map((f) => (
        <Disclosure key={f.id} id={f.id}>
          <DisclosureTrigger>{f.q}</DisclosureTrigger>
          <DisclosurePanel>{f.a}</DisclosurePanel>
        </Disclosure>
      ))}
    </DisclosureGroup>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/disclosure
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

```tsx
import {
  Disclosure,
  DisclosureGroup,
  DisclosurePanel,
  DisclosureTrigger,
} from "@/components/ui/disclosure";
```

```tsx
<DisclosureGroup>
  <Disclosure id="shipping">
    <DisclosureTrigger>Shipping</DisclosureTrigger>
    <DisclosurePanel>Free on orders over $50.</DisclosurePanel>
  </Disclosure>
  <Disclosure id="returns">
    <DisclosureTrigger>Returns</DisclosureTrigger>
    <DisclosurePanel>Return unworn items within 30 days.</DisclosurePanel>
  </Disclosure>
</DisclosureGroup>
```

A `DisclosureGroup` is an accordion: by default, opening one item closes the others. A `Disclosure` also works on its own, without a group.

### When to use

* Disclosure — optional or secondary content users can skip: FAQs, advanced settings, details on a product page, filter groups.
* [Tabs](/docs/components/tabs) — switch between peer views where exactly one is visible and none should be hidden by default.
* [Dialog](/docs/components/dialog) or [Popover](/docs/components/popover) — content that needs focus or shouldn't push the page down.
* Don't hide content most users need; long pages with clear headings are often easier to scan than a stack of collapsed sections.

## Anatomy

```tsx
<DisclosureGroup>             {/* optional: accordion, sets the variant */}
  <Disclosure>                {/* one section */}
    <DisclosureTrigger>       {/* <h3> › <button> with label and indicator */}
      <Icon />
      Label
    </DisclosureTrigger>
    <DisclosurePanel>         {/* collapsible content */}
      …
    </DisclosurePanel>
  </Disclosure>
</DisclosureGroup>
```

| Part                | Renders                            | Notes                                                                                                    |
| ------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `DisclosureGroup`   | `<div>`                            | Manages which items are expanded and passes `variant` to its items.                                      |
| `Disclosure`        | `<div>`                            | One section. Needs an `id` inside a group for `expandedKeys`. Has the `group/disclosure` class.          |
| `DisclosureTrigger` | `<h3>` › `<button slot="trigger">` | Full-width button with the children on the left and the indicator on the right.                          |
| Indicator           | `<svg>`                            | Chevron (rotates 180°) or plus (rotates 45° into a ×). `aria-hidden`.                                    |
| `DisclosurePanel`   | `<div role="group">` › `<div>`     | The collapsible region. The outer element animates its height; the inner one gets the variant's padding. |

## Examples

### Card

`variant="card"` wraps the whole group in one bordered card with dividers, and tints the open item's trigger. Icons in the trigger are sized to 16px and muted.

Example `disclosure/card`: source in https://desyne.dev/docs/components/disclosure.md

### Separated

`variant="separated"` gives each item its own card with a gap between them. The open item gets a slightly stronger shadow. Suits FAQs and marketing pages.

Example `disclosure/separated`: source in https://desyne.dev/docs/components/disclosure.md

### Indicators

`indicator="chevron"` (default) rotates to point up when open. `indicator="plus"` turns into a × and reads well in FAQ lists.

Example `disclosure/indicators`: source in https://desyne.dev/docs/components/disclosure.md

### Multiple expanded

`allowsMultipleExpanded` lets users open several items at once. Use it when items are independent and users may compare them, like product details or filters.

Example `disclosure/multiple`: source in https://desyne.dev/docs/components/disclosure.md

### Rich trigger

The trigger's children are laid out in a row with `gap-2`, so icons, monospace labels and [`Badge`](/docs/components/badge)s line up. Keep interactive elements out of the trigger; it's already a button.

Example `disclosure/rich-trigger`: source in https://desyne.dev/docs/components/disclosure.md

### Standalone

A single `Disclosure` without a group uses the `line` styles. It draws a bottom border by default; remove it with `border-b-0` when it isn't part of a list.

Example `disclosure/single`: source in https://desyne.dev/docs/components/disclosure.md

### Disabled

`isDisabled` on a `Disclosure` stops it from toggling and dims its trigger. `isDisabled` on `DisclosureGroup` disables every item. Explain why in the trigger text or nearby.

Example `disclosure/disabled`: source in https://desyne.dev/docs/components/disclosure.md

### Controlled

Pass `expandedKeys` and `onExpandedChange` to `DisclosureGroup` to own the state, for example for Expand all and Collapse all buttons. For a single `Disclosure`, use `isExpanded` and `onExpandedChange`.

Example `disclosure/controlled`: source in https://desyne.dev/docs/components/disclosure.md

### Custom trigger

`DisclosureTrigger` always renders a heading and a full-width button. For a different layout, put any React Aria button with `slot="trigger"` inside the `Disclosure`, such as a link-style [`Button`](/docs/components/button) below a preview. It gets `aria-expanded` and `aria-controls` automatically, and `group-data-expanded/disclosure:` classes can react to the state.

Example `disclosure/custom-trigger`: source in https://desyne.dev/docs/components/disclosure.md

## Recipes

### FAQ section

A two-column FAQ with a heading, a [`Link`](/docs/components/link) to contact support, and plus indicators.

Example `disclosure/recipe-faq`: source in https://desyne.dev/docs/components/disclosure.md

### Filter panel

Filter groups in a shop sidebar, each a disclosure containing a [`CheckboxGroup`](/docs/components/checkbox). Multiple groups can be open at once.

Example `disclosure/recipe-filters`: source in https://desyne.dev/docs/components/disclosure.md

### Order summary

A standalone disclosure for a checkout summary on mobile: the total stays visible in the trigger and the line items expand below.

Example `disclosure/recipe-order-summary`: source in https://desyne.dev/docs/components/disclosure.md

## Accessibility

* Each trigger is a `<button>` with `aria-expanded` and `aria-controls` pointing at its panel, inside an `<h3>` so sections appear in the heading outline.
* The panel has `role="group"` by default and is labelled by its trigger. Pass `role="region"` to `DisclosurePanel` for important sections that should be landmarks; use it sparingly.
* Collapsed panels use `hidden="until-found"` where the browser supports it, so find-in-page can reveal and expand them.
* The height animation is disabled when the user prefers reduced motion.
* Triggers use their text as the accessible name; icons and indicators are decorative.

### Keyboard

| Key                                              | Action                                                      |
| ------------------------------------------------ | ----------------------------------------------------------- |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between triggers and focusable content in open panels |
| <kbd>Space</kbd> / <kbd>Enter</kbd>              | Expands or collapses the focused section                    |

## Styling

### Data attributes

| Attribute                       | On                              | Present when                        |
| ------------------------------- | ------------------------------- | ----------------------------------- |
| `data-expanded`                 | `Disclosure`                    | The section is open                 |
| `data-disabled`                 | `Disclosure`, `DisclosureGroup` | Disabled                            |
| `data-focus-visible-within`     | `Disclosure`, `DisclosurePanel` | Something inside has keyboard focus |
| `data-hovered` / `data-pressed` | trigger button                  | Hovered / being pressed             |
| `data-focus-visible`            | trigger button                  | Focused with the keyboard           |

Each `Disclosure` has the `group/disclosure` class, so any child can react to its state with `group-data-expanded/disclosure:…`, as the indicator does.

### Slots

| `data-slot`        | Element                    |
| ------------------ | -------------------------- |
| `disclosure-group` | Group root                 |
| `disclosure`       | Each item                  |
| `disclosure-panel` | Each panel (outer element) |

### Animation

The panel animates `height` to the `--disclosure-panel-height` variable that React Aria sets when it opens and closes (`h-(--disclosure-panel-height) overflow-hidden transition-[height] duration-200`). Reuse the same classes on your own `DisclosurePanel` from React Aria to get the same motion.

### Customizing

* `className` on `DisclosureGroup`, `Disclosure` and `DisclosurePanel` accepts a string or a function of their render props.
* `className` on `DisclosureTrigger` goes to the button, e.g. `className="py-2 text-xs"` for denser lists.
* The panel's padding and text color come from the variant and are on its inner element. Override them with a child wrapper or `[&>div]:…` on `DisclosurePanel`.

## API Reference

### DisclosureGroup

<TypeTable
  type="{
  variant: { type: '&#x22;line&#x22; | &#x22;card&#x22; | &#x22;separated&#x22;', default: '&#x22;line&#x22;', description: &#x22;Group style, shared with every item inside.&#x22; },
  allowsMultipleExpanded: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Allow more than one item open at a time.&#x22; },
  expandedKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Open items (controlled).&#x22; },
  defaultExpandedKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Initially open items (uncontrolled).&#x22; },
  onExpandedChange: { type: &#x22;(keys: Set<Key>) => void&#x22;, description: &#x22;Called when items open or close.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Disables every item.&#x22; },
  className: { type: &#x22;string | ((state: DisclosureGroupRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: DisclosureGroupRenderProps) => ReactNode)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`DisclosureGroup`](https://react-aria.adobe.com/Disclosure).

### Disclosure

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Key used by the group's expandedKeys.&#x22; },
  isExpanded: { type: &#x22;boolean&#x22;, description: &#x22;Open state (controlled). For standalone disclosures.&#x22; },
  defaultExpanded: { type: &#x22;boolean&#x22;, description: &#x22;Initial open state (uncontrolled). For standalone disclosures.&#x22; },
  onExpandedChange: { type: &#x22;(isExpanded: boolean) => void&#x22;, description: &#x22;Called when the item opens or closes.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Stops the item from toggling.&#x22; },
  className: { type: &#x22;string | ((state: DisclosureRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: DisclosureRenderProps) => ReactNode)&#x22;, description: &#x22;A trigger and a panel, or a function of { isExpanded, isDisabled, … }.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Disclosure`](https://react-aria.adobe.com/Disclosure#api).

### DisclosureTrigger

<TypeTable
  type="{
  indicator: { type: '&#x22;chevron&#x22; | &#x22;plus&#x22;', default: '&#x22;chevron&#x22;', description: &#x22;Icon on the right and how it animates when open.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the button.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Label, with optional icon and badge.&#x22; },
}"
/>

`DisclosureTrigger` takes only these props. It renders an `<h3>`; for another heading level or other button props, use a custom trigger with `slot="trigger"`.

### DisclosurePanel

<TypeTable
  type="{
  role: { type: '&#x22;group&#x22; | &#x22;region&#x22;', default: '&#x22;group&#x22;', description: &#x22;Accessibility role of the panel.&#x22; },
  className: { type: &#x22;string | ((state: DisclosurePanelRenderProps) => string)&#x22;, description: &#x22;Classes for the animated outer element.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Panel content.&#x22; },
}"
/>

## Related

* [Tabs](/docs/components/tabs) — switch between views, one at a time.
* [Sidebar](/docs/components/sidebar) — uses a Disclosure for collapsible submenus.
* [Checkbox](/docs/components/checkbox) — common content for filter panels.
* [Card](/docs/components/card) — a container for a standalone disclosure.

---

# Sidebar

Source: https://desyne.dev/docs/components/sidebar

> A composable application sidebar. Collapses off-canvas or to an icon rail, comes in sidebar, floating and inset styles, turns into a modal sheet on small screens, and toggles with ⌘B / Ctrl+B. Menu items can be links or buttons, with badges, groups and tooltips in icon mode.

```tsx title="sidebar/demo.tsx"
"use client";

import {
  FolderIcon,
  HomeIcon,
  InboxIcon,
  SearchIcon,
  SettingsIcon,
} from "lucide-react";
import { Avatar } from "@/components/ui/avatar";
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarTrigger,
} from "@/components/ui/sidebar";

const items = [
  { title: "Home", icon: HomeIcon, active: true },
  { title: "Inbox", icon: InboxIcon, badge: "12" },
  { title: "Search", icon: SearchIcon },
  { title: "Projects", icon: FolderIcon },
  { title: "Settings", icon: SettingsIcon },
];

export default function SidebarDemo() {
  return (
    // data-sidebar-contained keeps the sidebar inside this box; omit it in a real app layout.
    <div
      data-sidebar-contained
      className="relative h-[420px] w-full overflow-hidden rounded-lg border"
    >
      <SidebarProvider className="h-full min-h-0">
        <Sidebar collapsible="icon">
          <SidebarHeader>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="lg" tooltip="Acme Inc">
                  <span className="flex size-8 shrink-0 items-center justify-center rounded-md bg-primary font-semibold text-primary-foreground text-xs">
                    A
                  </span>
                  <span className="flex flex-col leading-tight">
                    <span className="font-medium">Acme Inc</span>
                    <span className="text-muted-foreground text-xs">
                      Enterprise
                    </span>
                  </span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarHeader>
          <SidebarContent>
            <SidebarGroup>
              <SidebarGroupLabel>Application</SidebarGroupLabel>
              <SidebarMenu>
                {items.map((item) => (
                  <SidebarMenuItem key={item.title}>
                    <SidebarMenuButton
                      href="#"
                      isActive={item.active}
                      tooltip={item.title}
                    >
                      <item.icon />
                      <span>{item.title}</span>
                    </SidebarMenuButton>
                    {item.badge && (
                      <SidebarMenuBadge>{item.badge}</SidebarMenuBadge>
                    )}
                  </SidebarMenuItem>
                ))}
              </SidebarMenu>
            </SidebarGroup>
          </SidebarContent>
          <SidebarFooter>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton size="lg" tooltip="Nischal">
                  <Avatar size="md" shape="square" fallback="NT" />
                  <span className="flex flex-col leading-tight">
                    <span className="font-medium">Nischal</span>
                    <span className="text-muted-foreground text-xs">
                      nischal@example.com
                    </span>
                  </span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarFooter>
        </Sidebar>
        <SidebarInset>
          <header className="flex h-12 items-center gap-2 border-b px-3">
            <SidebarTrigger />
            <span className="font-medium text-sm">Home</span>
          </header>
          <div className="grid flex-1 grid-cols-3 gap-3 p-4">
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="rounded-lg bg-muted" />
            <div className="col-span-3 rounded-lg bg-muted" />
          </div>
        </SidebarInset>
      </SidebarProvider>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/sidebar
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

```tsx
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuBadge,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarSeparator,
  SidebarTrigger,
  useSidebar,
} from "@/components/ui/sidebar";
```

```tsx title="app/(app)/layout.tsx"
export default function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <SidebarProvider>
      <Sidebar collapsible="icon">
        <SidebarHeader>{/* workspace switcher */}</SidebarHeader>
        <SidebarContent>
          <SidebarGroup>
            <SidebarGroupLabel>Application</SidebarGroupLabel>
            <SidebarMenu>
              <SidebarMenuItem>
                <SidebarMenuButton href="/inbox" tooltip="Inbox">
                  <InboxIcon />
                  <span>Inbox</span>
                </SidebarMenuButton>
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarGroup>
        </SidebarContent>
        <SidebarFooter>{/* user menu */}</SidebarFooter>
      </Sidebar>
      <SidebarInset>
        <header>
          <SidebarTrigger />
        </header>
        {children}
      </SidebarInset>
    </SidebarProvider>
  );
}
```

`SidebarProvider` owns the open state and renders the layout wrapper (`min-h-svh`, full width, flex row). `Sidebar` reserves its width in that row and positions the panel `fixed` to the viewport, so the page content in `SidebarInset` never sits underneath it.

<Callout title="Rendering inside a box">
  The sidebar is fixed to the viewport by default. To keep it inside a
  bounded element (a preview, a modal, a dashboard widget), give an ancestor
  `data-sidebar-contained` and `relative`. The panel then uses absolute
  positioning and the ancestor's height. Every preview on this page does
  this, and sets `className="h-full min-h-0"` on `SidebarProvider`.
</Callout>

### When to use

* Sidebar — persistent primary navigation for an application with several top-level sections, especially when users switch between them often.
* [Tabs](/docs/components/tabs) — a handful of sibling views within one page or object.
* [Sheet](/docs/components/sheet) — temporary, secondary content that slides in over the page. On small screens the sidebar already uses a sheet for you.
* [Menu](/docs/components/menu) — a list of actions, or navigation that should stay hidden until requested. Use it inside the sidebar for workspace and account switchers.

## Anatomy

```tsx
<SidebarProvider>                  {/* state, shortcut, CSS variables, layout row */}
  <Sidebar>                        {/* panel: desktop column or mobile sheet */}
    <SidebarHeader />              {/* top: switcher, search */}
    <SidebarContent>               {/* scrolls */}
      <SidebarGroup>
        <SidebarGroupLabel />
        <SidebarMenu>
          <SidebarMenuItem>
            <SidebarMenuButton />  {/* link (href) or button */}
            <SidebarMenuBadge />   {/* optional count */}
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarGroup>
    </SidebarContent>
    <SidebarSeparator />
    <SidebarFooter />              {/* bottom: user menu, help */}
  </Sidebar>
  <SidebarInset>                   {/* main content */}
    <SidebarTrigger />
  </SidebarInset>
</SidebarProvider>
```

| Part                              | Renders                                                                        | Notes                                                                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `SidebarProvider`                 | `<div>`                                                                        | Provides context, the ⌘B / Ctrl+B shortcut and the `--sidebar-width` variables. Wraps both the sidebar and the inset.     |
| `Sidebar`                         | `<div>` (desktop), `Modal` › `Dialog` (mobile), `<div>` (`collapsible="none"`) | The panel. On desktop it renders a spacer (`sidebar-gap`) plus a fixed container (`sidebar-container` › `sidebar-inner`). |
| `SidebarTrigger`                  | [`Button`](/docs/components/button)                                            | Ghost icon button that calls `toggleSidebar()`. Renders its children in place of the default icon.                        |
| `SidebarInset`                    | `<main>`                                                                       | The page content next to the sidebar. Gets a margin, border and rounded corners when the sidebar uses `variant="inset"`.  |
| `SidebarHeader` / `SidebarFooter` | `<div>`                                                                        | Fixed regions above and below the content.                                                                                |
| `SidebarContent`                  | `<div>`                                                                        | Takes the remaining height and scrolls. Overflow is hidden in icon mode.                                                  |
| `SidebarGroup`                    | `<div>`                                                                        | A section of the sidebar.                                                                                                 |
| `SidebarGroupLabel`               | `<div>`                                                                        | Small uppercase heading. Fades out and collapses in icon mode.                                                            |
| `SidebarMenu`                     | `<ul>`                                                                         | A list of menu items.                                                                                                     |
| `SidebarMenuItem`                 | `<li>`                                                                         | Positions a button and its badge.                                                                                         |
| `SidebarMenuButton`               | `Link` (`<a>`) or `Button`                                                     | A link when `href` is set (with `aria-current="page"` when active), a button otherwise. Optional tooltip in icon mode.    |
| `SidebarMenuBadge`                | `<div>`                                                                        | Count or status at the end of a menu item. Hidden in icon mode.                                                           |
| `SidebarSeparator`                | [`Separator`](/docs/components/separator)                                      | Horizontal rule with the sidebar border color.                                                                            |

## Examples

### Variants

`variant` changes how the panel sits in the layout. `sidebar` (default) is a full-height column with a border. `floating` insets the panel with a margin, rounded corners and a shadow.

Example `sidebar/floating`: source in https://desyne.dev/docs/components/sidebar.md

`inset` puts the panel on the `sidebar` background and turns `SidebarInset` into a raised, rounded card. Use it for dashboards where the content should read as one surface.

Example `sidebar/inset`: source in https://desyne.dev/docs/components/sidebar.md

It works on either side. With `side="right"`, render `SidebarInset` before the `Sidebar` (as for any right sidebar); the card drops its margin on the side next to the panel.

Example `sidebar/inset-right`: source in https://desyne.dev/docs/components/sidebar.md

### Collapsible modes

`collapsible` controls what happens when the sidebar is closed on desktop: `offcanvas` (default) slides it out of view, `icon` shrinks it to a 3rem rail of icons, and `none` renders a static panel that can't collapse. Switch modes in the preview and press the trigger.

Example `sidebar/collapsible`: source in https://desyne.dev/docs/components/sidebar.md

In icon mode, group labels and badges hide, menu buttons become 32px squares, and text in the last `<span>` of each button is clipped. Set `tooltip` on every `SidebarMenuButton` so collapsed items keep a visible label on hover and focus.

### Right side

`side="right"` docks the panel on the right, for details and inspector panels. Render `SidebarInset` before the `Sidebar` so the space is reserved on the correct side. On mobile the sheet slides in from the right. Pass an icon as the trigger's children to point it the right way.

Example `sidebar/right`: source in https://desyne.dev/docs/components/sidebar.md

### Groups and footer

Split long navigation into `SidebarGroup`s with a `SidebarGroupLabel` each. `SidebarFooter` stays pinned to the bottom while `SidebarContent` scrolls; a `SidebarSeparator` divides them.

Example `sidebar/groups`: source in https://desyne.dev/docs/components/sidebar.md

### Menu button sizes

`size="lg"` (48px) for workspace and user switchers with two lines of text, `default` (32px) for primary navigation, and `sm` (28px) for dense or secondary lists.

Example `sidebar/menu-sizes`: source in https://desyne.dev/docs/components/sidebar.md

### Collapsible submenus

Nest a `SidebarMenu` inside a React Aria `Disclosure`, and give the `SidebarMenuButton` `slot="trigger"` to toggle it. The button gets `aria-expanded` automatically. Animate the panel height with `--disclosure-panel-height`, as the [Disclosure](/docs/components/disclosure) component does.

Example `sidebar/submenu`: source in https://desyne.dev/docs/components/sidebar.md

### Active item and routing

Mark the current page with `isActive`; for links it also sets `aria-current="page"`. Derive it from your router's current path, and wrap the app in React Aria's `RouterProvider` so menu links use client-side navigation. The preview uses a local stand-in for the router.

Example `sidebar/router`: source in https://desyne.dev/docs/components/sidebar.md

With the Next.js App Router:

```tsx title="app/providers.tsx"
"use client";

import { useRouter } from "next/navigation";
import { RouterProvider } from "react-aria-components";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <RouterProvider navigate={router.push}>{children}</RouterProvider>;
}
```

```tsx title="components/nav-main.tsx"
"use client";

import { usePathname } from "next/navigation";

export function NavMain({ items }: { items: { href: string; title: string; icon: React.ElementType }[] }) {
  const pathname = usePathname();
  return (
    <SidebarMenu>
      {items.map((item) => (
        <SidebarMenuItem key={item.href}>
          <SidebarMenuButton href={item.href} isActive={pathname === item.href} tooltip={item.title}>
            <item.icon />
            <span>{item.title}</span>
          </SidebarMenuButton>
        </SidebarMenuItem>
      ))}
    </SidebarMenu>
  );
}
```

### Controlled

Pass `open` and `onOpenChange` to `SidebarProvider` to own the desktop state, for example to persist it in a cookie or user setting. On desktop, the trigger, the keyboard shortcut and anything calling `setOpen` all go through `onOpenChange`. The mobile sheet keeps its own state.

Example `sidebar/controlled`: source in https://desyne.dev/docs/components/sidebar.md

```tsx
// Persist the state between visits.
const [open, setOpen] = useState(defaultOpenFromCookie);

<SidebarProvider
  open={open}
  onOpenChange={(value) => {
    setOpen(value);
    document.cookie = `sidebar_state=${value}; path=/; max-age=31536000`;
  }}
/>;
```

### useSidebar

Any component inside `SidebarProvider` can read and change the state with `useSidebar()`. Use it for custom triggers, or to adapt content to the collapsed state. It throws if called outside a provider.

Example `sidebar/use-sidebar`: source in https://desyne.dev/docs/components/sidebar.md

### Static sidebar

`collapsible="none"` renders a plain, always-visible `<div>` with no container, spacer or mobile sheet. Use it for secondary navigation inside a page, such as settings.

It stays inline on every screen size, as in shadcn/ui: below 768px it doesn't become a sheet or hide, and `SidebarTrigger` and the shortcut don't affect it. It's a normal flex item, so it never overlays the page, but in a row it shrinks with the layout; on narrow screens you may want to stack it above the content or swap it for a [Select](/docs/components/select) or [Tabs](/docs/components/tabs).

Example `sidebar/none`: source in https://desyne.dev/docs/components/sidebar.md

### Mobile

Below 768px (`max-width: 767px`) the desktop panel is hidden, and `Sidebar` renders as a modal sheet from its `side` instead. The trigger and the shortcut toggle the sheet (`openMobile`), which is separate from the desktop `open` state, so collapsing on desktop doesn't affect mobile. The sheet has a backdrop, traps focus, and closes on <kbd>Esc</kbd> or an outside click.

Pressing a link inside the sheet closes it, with the mouse, touch or <kbd>Enter</kbd>. This covers any `<a href>` in the sheet, whether it's a `SidebarMenuButton` link or a link in your own markup. Clicks that open a new tab or window (with a modifier key, `target="_blank"` or `download`) leave it open, and so do button items. Pass `closeOnNavigate={false}` to keep the sheet open, or call `setOpenMobile(false)` from `useSidebar()` to close it after a button press.

`className` and `style` on `Sidebar` also apply to the sheet. Use `max-md:` classes to style only the sheet, and `md:` classes to style only the desktop panel.

Example `sidebar/mobile`: source in https://desyne.dev/docs/components/sidebar.md

The breakpoint is based on the viewport width (via `useIsMobile()`), not the container, so contained previews on a wide screen always show the desktop sidebar. Resize the browser window to see the sheet.

## Recipes

### App shell

An `inset` sidebar with icon collapsing: a workspace switcher [`Menu`](/docs/components/menu) in the header, primary navigation with a badge, a projects group, and an account menu in the footer. The content area has a trigger and [`Breadcrumbs`](/docs/components/breadcrumbs).

Example `sidebar/recipe-app-shell`: source in https://desyne.dev/docs/components/sidebar.md

### Mail

Folders and labels with unread counts in `SidebarMenuBadge`. The Compose button reads `useSidebar()` to collapse to an icon and show its tooltip only in icon mode, matching the menu buttons.

Example `sidebar/recipe-mail`: source in https://desyne.dev/docs/components/sidebar.md

### Documentation

A documentation layout: title and [`SearchField`](/docs/components/search-field) in the header, small link items grouped by section, and a scrolling content area.

Example `sidebar/recipe-docs`: source in https://desyne.dev/docs/components/sidebar.md

## Accessibility

* `SidebarMenuButton` renders a real link when given `href`, with `aria-current="page"` when `isActive`, so middle-click, "open in new tab" and screen-reader link lists work. Without `href` it's a button.
* Wrap navigation in landmarks as your layout needs; `SidebarInset` renders the page's `<main>`.
* In icon mode, give every `SidebarMenuButton` a `tooltip`. The text stays in the DOM and keeps naming the item for assistive tech; the tooltip gives sighted users the same label.
* Tooltips only show when the sidebar is collapsed to icons on desktop; they're disabled when expanded and on mobile.
* `SidebarTrigger` has `aria-label="Toggle sidebar"`. Pass your own `aria-label` to change it.
* On mobile the sidebar is a modal `Dialog` labelled "Sidebar": focus moves into it, is trapped while open and returns to the trigger on close.
* The ⌘B / Ctrl+B shortcut is registered on `window` by each `SidebarProvider` and calls `preventDefault()`, so it replaces any browser or editor shortcut on the same keys while the page is focused. Advertise it with a [`Kbd`](/docs/components/kbd) hint.

### Keyboard

| Key                                                      | Action                                        |
| -------------------------------------------------------- | --------------------------------------------- |
| <kbd>⌘</kbd>+<kbd>B</kbd> / <kbd>Ctrl</kbd>+<kbd>B</kbd> | Toggles the sidebar (the sheet on mobile)     |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>         | Moves between menu items and other controls   |
| <kbd>Enter</kbd>                                         | Follows a link item, or presses a button item |
| <kbd>Space</kbd>                                         | Presses a button item (or a submenu trigger)  |
| <kbd>Esc</kbd>                                           | Closes the mobile sheet                       |

## Styling

### Data attributes

On the desktop `Sidebar` root (`data-slot="sidebar"`, which also has the `group` and `peer` classes):

| Attribute          | Values                                                                               |
| ------------------ | ------------------------------------------------------------------------------------ |
| `data-state`       | `expanded` or `collapsed`                                                            |
| `data-collapsible` | The `collapsible` mode while collapsed (`offcanvas` or `icon`); empty while expanded |
| `data-variant`     | `sidebar`, `floating` or `inset`                                                     |
| `data-side`        | `left` or `right`                                                                    |

Style anything inside the sidebar by state with `group-data-*`, for example `group-data-[collapsible=icon]:hidden` to hide an element in icon mode. Style siblings after it with `peer-data-*`. `SidebarInset` styles itself for the inset variant from the wrapper (`group-has-*` on `sidebar-wrapper`), so it works whether it comes before or after the `Sidebar`. The mobile sheet instead has `data-slot="sidebar"`, `data-mobile="true"` and `data-side`.

On `SidebarMenuButton`:

| Attribute                             | Present when                                     |
| ------------------------------------- | ------------------------------------------------ |
| `data-active`                         | `"true"` when `isActive`, `"false"` otherwise    |
| `data-hovered` / `data-pressed`       | Hovered / being pressed                          |
| `data-focused` / `data-focus-visible` | Focused / focused with the keyboard              |
| `data-disabled`                       | `isDisabled` is true                             |
| `data-current`                        | Link items with `isActive` (from `aria-current`) |

### Slots

| `data-slot`                                                                      | Element                                             |
| -------------------------------------------------------------------------------- | --------------------------------------------------- |
| `sidebar-wrapper`                                                                | `SidebarProvider` root                              |
| `sidebar`                                                                        | `Sidebar` root                                      |
| `sidebar-gap`                                                                    | Spacer that reserves the sidebar's width on desktop |
| `sidebar-container`                                                              | The fixed (or contained absolute) panel on desktop  |
| `sidebar-inner`                                                                  | The panel's background surface                      |
| `sidebar-trigger`                                                                | `SidebarTrigger`                                    |
| `sidebar-inset`                                                                  | `SidebarInset`                                      |
| `sidebar-header`, `sidebar-content`, `sidebar-footer`                            | Regions                                             |
| `sidebar-group`, `sidebar-group-label`                                           | Groups                                              |
| `sidebar-menu`, `sidebar-menu-item`, `sidebar-menu-button`, `sidebar-menu-badge` | Menu parts                                          |
| `sidebar-separator`                                                              | `SidebarSeparator`                                  |

### CSS variables

| Variable               | Default | Used for                           |
| ---------------------- | ------- | ---------------------------------- |
| `--sidebar-width`      | `16rem` | Expanded width, desktop and mobile |
| `--sidebar-width-icon` | `3rem`  | Width in icon mode                 |

Set them on `SidebarProvider` with `style`:

```tsx
<SidebarProvider
  style={{ "--sidebar-width": "18rem", "--sidebar-width-icon": "3.5rem" } as React.CSSProperties}
/>
```

The colors come from theme tokens: `--sidebar` (background), `--sidebar-foreground`, `--sidebar-border`, `--sidebar-accent` and `--sidebar-accent-foreground` (active item), `--sidebar-primary` (active item icon) and `--sidebar-ring`. See [Theming](/docs/theming).

### Customizing

* On desktop, `className` and other props on `Sidebar` go to `sidebar-container`, the fixed panel. With `collapsible="none"` they go to the root `<div>`. On mobile, `className` and `style` go to the sheet (the `Modal`); other `<div>` props aren't applied there.
* `SidebarMenuButton` truncates its last `<span>`, so wrap labels in a `<span>` and put icons first.
* `SidebarMenuBadge` is absolutely positioned for the `default` button height. Add padding to the button (`pr-8`) if long labels could run under it.

### `sidebarMenuButtonVariants`

The `tailwind-variants` function behind `SidebarMenuButton`. Use it to give other elements, such as a Next.js `Link`, the look of a menu item.

```tsx
import { sidebarMenuButtonVariants } from "@/components/ui/sidebar";

sidebarMenuButtonVariants({ size: "sm" });
```

## API Reference

### SidebarProvider

<TypeTable
  type="{
  defaultOpen: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Initial desktop state (uncontrolled).&#x22; },
  open: { type: &#x22;boolean&#x22;, description: &#x22;Desktop open state (controlled). Use with onOpenChange.&#x22; },
  onOpenChange: { type: &#x22;(open: boolean) => void&#x22;, description: &#x22;Called when the desktop state changes, from the trigger, shortcut or setOpen.&#x22; },
  style: { type: &#x22;CSSProperties&#x22;, description: &#x22;Merged after the default --sidebar-width and --sidebar-width-icon, so you can override them.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the wrapper. It has min-h-svh by default.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Usually a Sidebar and a SidebarInset.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### Sidebar

<TypeTable
  type="{
  side: { type: '&#x22;left&#x22; | &#x22;right&#x22;', default: '&#x22;left&#x22;', description: &#x22;Which edge the panel (and the mobile sheet) sits on.&#x22; },
  variant: { type: '&#x22;sidebar&#x22; | &#x22;floating&#x22; | &#x22;inset&#x22;', default: '&#x22;sidebar&#x22;', description: &#x22;How the panel sits in the layout.&#x22; },
  collapsible: { type: '&#x22;offcanvas&#x22; | &#x22;icon&#x22; | &#x22;none&#x22;', default: '&#x22;offcanvas&#x22;', description: &#x22;What collapsing does on desktop. none renders a static, inline panel on every screen size, with no mobile sheet.&#x22; },
  closeOnNavigate: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Close the mobile sheet when a link inside it is pressed. Clicks that open a new tab or window keep it open.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the panel container (desktop), the sheet (mobile) or the root (none).&#x22; },
  style: { type: &#x22;CSSProperties&#x22;, description: &#x22;Styles for the same element as className.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Header, content, footer and separators.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### SidebarMenuButton

<TypeTable
  type="{
  href: { type: &#x22;string&#x22;, description: &#x22;Renders a React Aria Link. Without it, a React Aria Button.&#x22; },
  isActive: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Marks the current item. Sets data-active, and aria-current=\&#x22;page\&#x22; on links.&#x22; },
  tooltip: { type: &#x22;string&#x22;, description: &#x22;Label shown in a tooltip on the right when the sidebar is collapsed to icons (desktop only).&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;default&#x22; | &#x22;lg&#x22;', default: '&#x22;default&#x22;', description: &#x22;Height: 28px, 32px or 48px.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Called when the item is pressed.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables the item.&#x22; },
  slot: { type: &#x22;string&#x22;, description: 'React Aria slot, e.g. &#x22;trigger&#x22; inside a Disclosure. Button items only.' },
  target: { type: &#x22;string&#x22;, description: &#x22;Link target. Link items only.&#x22; },
  routerOptions: { type: &#x22;RouterOptions&#x22;, description: &#x22;Options passed to your router's navigate function. Link items only.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with sidebarMenuButtonVariants.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;An icon followed by a <span> label.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Link`](https://react-aria.adobe.com/Link#api) (with `href`) or [`Button`](https://react-aria.adobe.com/Button#api) (without).

### SidebarTrigger

A ghost, `icon-sm` [`Button`](/docs/components/button) with a panel icon. Pass children to replace the icon, for example `<PanelRightIcon />` for a right sidebar, or text with `size="sm"`. It keeps `aria-label="Toggle sidebar"` unless you pass your own, so with visible text pass a matching `aria-label` (or `aria-label={undefined}`). Accepts every button prop; `onPress` runs before the sidebar toggles.

### SidebarInset

Accepts every prop of `<main>`.

### SidebarHeader / SidebarFooter / SidebarContent / SidebarGroup / SidebarGroupLabel / SidebarMenuBadge

Accept every prop of `<div>`.

### SidebarMenu / SidebarMenuItem

Accept every prop of `<ul>` / `<li>`.

### SidebarSeparator

Accepts every prop of [`Separator`](/docs/components/separator).

### useSidebar

Returns the sidebar state. Must be called inside `SidebarProvider`.

<TypeTable
  type="{
  state: { type: '&#x22;expanded&#x22; | &#x22;collapsed&#x22;', description: &#x22;Desktop state, derived from open.&#x22; },
  open: { type: &#x22;boolean&#x22;, description: &#x22;Whether the desktop sidebar is expanded.&#x22; },
  setOpen: { type: &#x22;(open: boolean) => void&#x22;, description: &#x22;Expands or collapses the desktop sidebar.&#x22; },
  openMobile: { type: &#x22;boolean&#x22;, description: &#x22;Whether the mobile sheet is open.&#x22; },
  setOpenMobile: { type: &#x22;(open: boolean) => void&#x22;, description: &#x22;Opens or closes the mobile sheet.&#x22; },
  isMobile: { type: &#x22;boolean&#x22;, description: &#x22;Whether the viewport is narrower than 768px.&#x22; },
  toggleSidebar: { type: &#x22;() => void&#x22;, description: &#x22;Toggles the sheet on mobile, the desktop sidebar otherwise.&#x22; },
}"
/>

### useIsMobile

`useIsMobile(): boolean` — `true` when `(max-width: 767px)` matches. Subscribes to the media query, and returns `false` during server rendering.

## Related

* [Sheet](/docs/components/sheet) — the modal panel the sidebar becomes on mobile.
* [Menu](/docs/components/menu) — workspace and account switchers.
* [Tooltip](/docs/components/tooltip) — labels for icon-only items.
* [Breadcrumbs](/docs/components/breadcrumbs) — show the current location in the content header.
* [Tabs](/docs/components/tabs) — navigation between views within a page.

---

# Stepper

Source: https://desyne.dev/docs/components/stepper

> Shows where the user is in a multi-step flow, such as onboarding, checkout or a setup wizard. Horizontal or vertical, with complete, current, upcoming and error states, optional descriptions and icons, two sizes, and pressable steps for moving back through the flow.

```tsx title="stepper/demo.tsx"
"use client";

import { useState } from "react";
import { Button } from "@/components/ui/button";
import { Step, Stepper } from "@/components/ui/stepper";

const steps = [
  { title: "Account", description: "Name and email" },
  { title: "Workspace", description: "Team and URL" },
  { title: "Billing", description: "Plan and payment" },
];

export default function StepperDemo() {
  const [current, setCurrent] = useState(1);
  return (
    <div className="flex w-full max-w-xl flex-col gap-6">
      <Stepper aria-label="Workspace setup" currentStep={current}>
        {steps.map((s) => (
          <Step key={s.title} title={s.title} description={s.description} />
        ))}
      </Stepper>
      <div className="flex justify-end gap-2">
        <Button
          variant="outline"
          isDisabled={current === 0}
          onPress={() => setCurrent((c) => c - 1)}
        >
          Back
        </Button>
        <Button
          isDisabled={current === steps.length}
          onPress={() => setCurrent((c) => c + 1)}
        >
          {current >= steps.length - 1 ? "Finish" : "Continue"}
        </Button>
      </div>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/stepper
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

```tsx
import { Step, Stepper } from "@/components/ui/stepper";
```

```tsx
<Stepper aria-label="Workspace setup" currentStep={1}>
  <Step title="Account" description="Name and email" />
  <Step title="Workspace" description="Team and URL" />
  <Step title="Billing" description="Plan and payment" />
</Stepper>
```

`currentStep` is the zero-based index of the active step. Steps before it are `complete`, the step itself is `current`, and later steps are `upcoming`. Set `status` on a `Step` to override this, for example to mark a step as `error`.

### When to use

* Stepper: a flow with a fixed number of ordered steps, where knowing what's left helps the user (onboarding, checkout, import wizards, KYC).
* [Tabs](/docs/components/tabs): sections the user can visit in any order.
* [Progress Bar](/docs/components/progress-bar): progress of a task the user isn't driving step by step.
* [Timeline](/docs/components/timeline): a record of events that already happened.

## Anatomy

```tsx
<Stepper>                 {/* <ol>, orientation, size, currentStep */}
  <Step title description>{/* <li>, data-status */}
    {/* indicator: number, check, cross or icon */}
    {/* title + description (a <button> when pressable) */}
    {/* connector to the next step */}
    {/* children: content under the title (vertical only) */}
  </Step>
</Stepper>
```

| Part      | Renders                        | Notes                                                                                                        |
| --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `Stepper` | `<ol>`                         | Ordered list. Pass `aria-label` to name the flow. Provides orientation, size and `currentStep` to its steps. |
| `Step`    | `<li>`                         | Sets `data-status` and `aria-current="step"` on the current step.                                            |
| Indicator | `<span>`                       | The step number (1-based, unpadded), a check when complete, a cross on error, or your `icon`.                |
| Trigger   | React Aria `Button` or `<div>` | A button when `onStepChange` is set and the step can be reached; otherwise plain text.                       |
| Connector | `<span>`                       | Line to the next step. Brand-colored once the step is complete. Not rendered after the last step.            |
| Content   | `<div>`                        | `children` of a `Step`, shown under the title in vertical steppers.                                          |

## Examples

### Vertical

`orientation="vertical"` stacks steps with the connector running down the left. Pass `children` to a `Step` to show content under its title, such as the active step's form.

Example `stepper/vertical`: source in https://desyne.dev/docs/components/stepper.md

### Pressable steps

With `onStepChange`, reachable steps render as buttons and pressing one calls the handler with its index. By default (`isLinear`), only steps up to `currentStep` are pressable, so users can go back but not skip ahead. Set `isLinear={false}` to allow any step.

Example `stepper/navigation`: source in https://desyne.dev/docs/components/stepper.md

### Error state and icons

`status="error"` shows a cross and turns the title red. Use `description` to say what went wrong. `icon` replaces the number (and the check or cross) with your own glyph.

Example `stepper/status`: source in https://desyne.dev/docs/components/stepper.md

### Sizes

`md` (32px indicators) is the default. `sm` (24px) suits dialogs, sidebars and dense headers.

Example `stepper/sizes`: source in https://desyne.dev/docs/components/stepper.md

## Accessibility

* The stepper is an `<ol>`, so screen readers announce the number of steps and each step's position. Give it an `aria-label` that names the flow, e.g. "Checkout".
* The current step gets `aria-current="step"` (on its button when pressable, otherwise on the `<li>`).
* Each step includes visually hidden status text ("Completed", "Current step", "Not started", "Error"), so status isn't conveyed by color or icon alone.
* Pressable steps are React Aria buttons: they work with mouse, touch and keyboard (Tab, then Enter or Space) and show a focus ring on keyboard focus. Unreachable steps aren't buttons, so they aren't in the tab order.
* The connector and indicator glyphs are decorative.
* A stepper doesn't move focus. When the step changes, move focus to the new step's heading or first field yourself.

## Styling

### Data attributes

| Attribute                                     | On                | Values                                        |
| --------------------------------------------- | ----------------- | --------------------------------------------- |
| `data-slot="stepper"`                         | `Stepper`         | Always                                        |
| `data-orientation`                            | `Stepper`         | `horizontal` · `vertical`                     |
| `data-slot="step"`                            | `Step`            | Always                                        |
| `data-status`                                 | `Step`            | `complete` · `current` · `upcoming` · `error` |
| `data-slot="step-indicator"`                  | Indicator         | Always                                        |
| `data-slot="step-trigger"`                    | Pressable trigger | When pressable                                |
| `data-slot="step-title"` / `step-description` | Text              | Always / with `description`                   |
| `data-slot="step-connector"`                  | Connector         | All but the last step                         |
| `data-slot="step-content"`                    | Children          | Vertical, with `children`                     |

`Step` sets the `group/step` group, so you can style its children by status:

```tsx
<Step className="group-data-[status=error]/step:..." title="Upload" />
```

## API Reference

### Stepper

<TypeTable
  type="{
  currentStep: { type: &#x22;number&#x22;, description: &#x22;Zero-based index of the current step. Earlier steps are complete, later ones upcoming.&#x22; },
  onStepChange: { type: &#x22;(index: number) => void&#x22;, description: &#x22;Makes reachable steps pressable. Called with the pressed step's index.&#x22; },
  isLinear: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;When true, only steps up to currentStep can be pressed.&#x22; },
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Layout direction.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Indicator size: 24px or 32px.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Names the flow for screen readers.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<ol>`.

### Step

<TypeTable
  type="{
  title: { type: &#x22;ReactNode&#x22;, description: &#x22;Step name.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Secondary line under the title.&#x22; },
  status: { type: '&#x22;complete&#x22; | &#x22;current&#x22; | &#x22;upcoming&#x22; | &#x22;error&#x22;', description: &#x22;Overrides the status derived from currentStep.&#x22; },
  icon: { type: &#x22;ReactNode&#x22;, description: &#x22;Replaces the number, check and cross in the indicator.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Dims the step and makes it not pressable.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Content under the title. Vertical steppers only.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<li>`.

## Related

* [Tabs](/docs/components/tabs): sections in any order.
* [Progress Bar](/docs/components/progress-bar): overall progress as a bar.
* [Timeline](/docs/components/timeline): a history of events.

---

# List Box

Source: https://desyne.dev/docs/components/list-box

> An always-visible list of options with single or multiple selection, sections, rich two-line items, links and actions, typeahead, drag and drop, grid layouts and infinite loading. It's the list inside Select and Combo Box.

```tsx title="list-box/demo.tsx"
"use client";

import { ListBox, ListBoxItem } from "@/components/ui/list-box";

export default function ListBoxDemo() {
  return (
    <ListBox
      aria-label="Environment"
      selectionMode="single"
      defaultSelectedKeys={["staging"]}
      className="w-56"
    >
      <ListBoxItem id="development">Development</ListBoxItem>
      <ListBoxItem id="staging">Staging</ListBoxItem>
      <ListBoxItem id="production">Production</ListBoxItem>
      <ListBoxItem id="preview" isDisabled>
        Preview (disabled)
      </ListBoxItem>
    </ListBox>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/list-box
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  ListBox,
  ListBoxItem,
  ListBoxItemDescription,
  ListBoxItemLabel,
  ListBoxSection,
} from "@/components/ui/list-box";
```

```tsx
<ListBox aria-label="Environment" selectionMode="single">
  <ListBoxItem id="development">Development</ListBoxItem>
  <ListBoxItem id="staging">Staging</ListBoxItem>
  <ListBoxItem id="production">Production</ListBoxItem>
</ListBox>
```

<Callout title="Options, not controls">
  List box items are `role="option"` and can't contain interactive elements
  like buttons, checkboxes or links inside them. If each row needs its own
  actions, use a [Grid List](/docs/components/grid-list) instead.
</Callout>

### When to use

* List Box — choosing one or more values from a visible list: a picker panel, a sidebar filter, a transfer list.
* [Select](/docs/components/select) / [Combo Box](/docs/components/combobox) — the same list in a popover, to save space in forms.
* [Grid List](/docs/components/grid-list) — rows that hold buttons, menus or checkboxes, or need drag handles.
* [Menu](/docs/components/menu) — a list of commands, not a value.
* [Checkbox Group](/docs/components/checkbox) / [Radio Group](/docs/components/radio-group) — a few options inside a form.

## Anatomy

```tsx
<ListBox>                          {/* role="listbox" */}
  <ListBoxSection title="…">       {/* optional group with a heading */}
    <ListBoxItem id="…">           {/* role="option" */}
      <Icon />
      <ListBoxItemLabel />         {/* accessible name */}
      <ListBoxItemDescription />   {/* accessible description */}
    </ListBoxItem>                 {/* checkmark added when selected */}
  </ListBoxSection>
</ListBox>
```

| Part                     | Renders                     | Notes                                                                                                                                |
| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ListBox`                | `<div role="listbox">`      | Scrollable, bordered panel (`bg-popover`). Shows `renderEmptyState` when empty.                                                      |
| `ListBoxItem`            | `<div role="option">`       | Needs a unique `id` (or comes from `items`). Adds a trailing check icon when selected. Plain-string children become the `textValue`. |
| `ListBoxItemLabel`       | `<span slot="label">`       | Primary text of a rich item, truncated.                                                                                              |
| `ListBoxItemDescription` | `<span slot="description">` | Secondary text, muted.                                                                                                               |
| `ListBoxSection`         | `<section role="group">`    | Groups items under an optional `title`, with a divider between sections.                                                             |
| `ListBoxLoadMoreItem`    | `<div>`                     | From `react-aria-components`. Triggers `onLoadMore` when scrolled into view.                                                         |

## Examples

### Selection modes

`selectionMode` is `none` by default (a static or actionable list), `single` or `multiple`.

Example `list-box/selection-modes`: source in https://desyne.dev/docs/components/list-box.md

### Controlled selection

`selectedKeys` and `onSelectionChange` own the selection. The value is a `Selection`: a `Set` of keys, or the string `"all"` after <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>A</kbd> or `setSelected("all")`, so handle both.

Example `list-box/controlled`: source in https://desyne.dev/docs/components/list-box.md

### Selection behavior

`selectionBehavior="replace"` makes a click select only that item, like a file browser. <kbd>⌘</kbd>/<kbd>Ctrl</kbd> and <kbd>Shift</kbd> add to or extend the selection; arrow keys move the selection with focus. The default `toggle` adds and removes items on every click.

Example `list-box/selection-behavior`: source in https://desyne.dev/docs/components/list-box.md

### Disabled items

`disabledKeys` keeps items visible but not focusable or selectable. `isDisabled` on a `ListBoxItem` does the same for one item.

Example `list-box/disabled`: source in https://desyne.dev/docs/components/list-box.md

### Sections

`ListBoxSection` groups items under a heading. Selection works across sections.

Example `list-box/sections`: source in https://desyne.dev/docs/components/list-box.md

### Dynamic sections

Pass nested data to `items` and render sections with a function; each section takes its own `items`. Every object needs an `id` (or `key`).

Example `list-box/dynamic-sections`: source in https://desyne.dev/docs/components/list-box.md

### Rich items

Compose icons with `ListBoxItemLabel` and `ListBoxItemDescription`. They're wired to the option's accessible name and description. Set `textValue` for typeahead when children aren't a plain string.

Example `list-box/rich-items`: source in https://desyne.dev/docs/components/list-box.md

### Actions

With `selectionMode="none"`, `onAction` turns items into actions (open, run, navigate). To combine actions with selection, use `selectionBehavior="replace"`: a click selects, and a double click or <kbd>Enter</kbd> triggers `onAction`.

Example `list-box/actions`: source in https://desyne.dev/docs/components/list-box.md

### Links

Give items an `href` (and optionally `target`) to render them as links. They navigate with a click or <kbd>Enter</kbd>, and work with client-side routers through React Aria's `RouterProvider`.

Example `list-box/links`: source in https://desyne.dev/docs/components/list-box.md

### Empty state

`renderEmptyState` renders when there are no items. The list gets `data-empty` and centered, muted text.

Example `list-box/empty`: source in https://desyne.dev/docs/components/list-box.md

### Infinite loading

Put the items in a `Collection` followed by `ListBoxLoadMoreItem`. When the sentinel scrolls into view it calls `onLoadMore`; `useAsyncList` manages pages, cursors and loading state. Give the list a fixed height so it scrolls.

Example `list-box/async`: source in https://desyne.dev/docs/components/list-box.md

### Drag to reorder

Pass `dragAndDropHooks` from `useDragAndDrop` and update your data in `onReorder`. `renderDropIndicator` with React Aria's `DropIndicator` draws the insertion line. Dragging works with mouse, touch, keyboard and screen readers.

Example `list-box/reorder`: source in https://desyne.dev/docs/components/list-box.md

### Grid layout

`layout="grid"` switches keyboard navigation to two dimensions, so arrow keys move up, down, left and right across a CSS grid. Here tiles hide the trailing checkmark and show selection with a ring instead.

Example `list-box/grid-layout`: source in https://desyne.dev/docs/components/list-box.md

## Recipes

### Searchable list

React Aria's `Autocomplete` connects a [`SearchField`](/docs/components/search-field) to the list: typing filters with `useFilter`, and arrow keys move through results while focus stays in the input.

Example `list-box/recipe-filterable`: source in https://desyne.dev/docs/components/list-box.md

### Transfer list

Two multi-select lists backed by `useListData`, with buttons to move the selection across. With `selectionBehavior="replace"`, a click selects and `onAction` (double click or <kbd>Enter</kbd>) moves a single item.

Example `list-box/recipe-transfer`: source in https://desyne.dev/docs/components/list-box.md

### Reviewer picker

Sections for suggested and team reviewers, [`Avatar`](/docs/components/avatar)s with two-line items, and a footer that reflects the controlled selection.

Example `list-box/recipe-reviewers`: source in https://desyne.dev/docs/components/list-box.md

## Accessibility

* The list is `role="listbox"` (with `aria-multiselectable` in multiple mode), and items are `role="option"` with `aria-selected`.
* Always label the list with `aria-label` or `aria-labelledby`.
* Focus is managed with a roving tab index: the list is one tab stop, and arrow keys move between items.
* Typeahead jumps to the next item whose `textValue` starts with the typed characters.
* Sections are `role="group"` labelled by their heading.
* `ListBoxItemLabel` and `ListBoxItemDescription` become the option's `aria-labelledby` and `aria-describedby`.
* Drag and drop exposes keyboard and screen reader interactions automatically, with announcements for each step.

### Keyboard

| Key                                                           | Action                                                                  |
| ------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <kbd>Tab</kbd>                                                | Moves focus into the list (to the selected or first item) and out again |
| <kbd>↑</kbd> / <kbd>↓</kbd>                                   | Moves focus to the previous / next item (←/→ too in grid layout)        |
| <kbd>Home</kbd> / <kbd>End</kbd>                              | Moves focus to the first / last item                                    |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                     | Moves focus by a page                                                   |
| <kbd>Space</kbd>                                              | Toggles selection of the focused item                                   |
| <kbd>Enter</kbd>                                              | Selects, or triggers `onAction` / follows the link                      |
| <kbd>Shift</kbd>+<kbd>↑</kbd> / <kbd>Shift</kbd>+<kbd>↓</kbd> | Extends the selection (multiple)                                        |
| <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>A</kbd>                     | Selects all (multiple)                                                  |
| <kbd>Esc</kbd>                                                | Clears the selection (unless `escapeKeyBehavior="none"`)                |
| Any character                                                 | Typeahead                                                               |

## Styling

### Data attributes

On the `ListBox`:

| Attribute                             | Present when                               |
| ------------------------------------- | ------------------------------------------ |
| `data-empty`                          | There are no items                         |
| `data-focused` / `data-focus-visible` | The list itself has focus / keyboard focus |
| `data-drop-target`                    | Something is being dragged over the list   |
| `data-layout`                         | Always: `stack` or `grid`                  |
| `data-orientation`                    | Always: `vertical` or `horizontal`         |

On each `ListBoxItem` (use `group-data-*/item:` inside it):

| Attribute                                | Present when                                                  |
| ---------------------------------------- | ------------------------------------------------------------- |
| `data-selected`                          | The item is selected                                          |
| `data-focused` / `data-focus-visible`    | The item has focus (including virtual focus) / keyboard focus |
| `data-hovered` / `data-pressed`          | Hovered with a mouse / being pressed                          |
| `data-disabled`                          | The item is disabled                                          |
| `data-selection-mode`                    | `single` or `multiple`                                        |
| `data-allows-dragging` / `data-dragging` | Drag and drop is enabled / the item is being dragged          |
| `data-drop-target`                       | The item is the current drop target                           |

### Slots

| `data-slot`        | Element      |
| ------------------ | ------------ |
| `list-box`         | Root         |
| `list-box-item`    | Each item    |
| `list-box-section` | Each section |

### Style helpers

`listBoxItemStyles` is the class string for items. Reuse it to make other option-like elements match:

```tsx
import { listBoxItemStyles } from "@/components/ui/list-box";
```

* The list has `max-h-[inherit]` and `overflow-auto`, so inside a popover it scrolls within the popover's height. Standalone, give it a `max-h-*` or `h-*`.
* Items reserve `pr-8` for the checkmark. Override with `className` when you hide it.
* Icons inside items are sized to `size-4` and muted unless they set their own `size-*` or `text-*` class.
* `className` on `ListBox` and `ListBoxItem` also accepts a function of the render props.

## API Reference

### ListBox

<TypeTable
  type="{
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static items and sections, or a render function.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;none&#x22;' },
  selectionBehavior: { type: '&#x22;toggle&#x22; | &#x22;replace&#x22;', default: '&#x22;toggle&#x22;', description: &#x22;How clicks and arrow keys affect selection.&#x22; },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Prevents deselecting the last item.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Items that can't be focused or selected.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when an item is actioned.&#x22; },
  renderEmptyState: { type: &#x22;(props: ListBoxRenderProps) => ReactNode&#x22;, description: &#x22;Content shown when there are no items.&#x22; },
  dragAndDropHooks: { type: &#x22;DragAndDropHooks&#x22;, description: &#x22;From useDragAndDrop, to enable drag and drop.&#x22; },
  layout: { type: '&#x22;stack&#x22; | &#x22;grid&#x22;', default: '&#x22;stack&#x22;', description: &#x22;grid enables two-dimensional keyboard navigation.&#x22; },
  orientation: { type: '&#x22;vertical&#x22; | &#x22;horizontal&#x22;', default: '&#x22;vertical&#x22;', description: &#x22;Primary direction of the items.&#x22; },
  shouldFocusWrap: { type: &#x22;boolean&#x22;, description: &#x22;Wraps focus from the last item to the first.&#x22; },
  shouldFocusOnHover: { type: &#x22;boolean&#x22;, description: &#x22;Moves focus to items on hover.&#x22; },
  shouldSelectOnPressUp: { type: &#x22;boolean&#x22;, description: &#x22;Selects on pointer up instead of down.&#x22; },
  escapeKeyBehavior: { type: '&#x22;clearSelection&#x22; | &#x22;none&#x22;', default: '&#x22;clearSelection&#x22;' },
  autoFocus: { type: 'boolean | &#x22;first&#x22; | &#x22;last&#x22;', description: &#x22;Focuses the list, or its first / last item, on mount.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that invalidate cached item rendering.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required unless you pass aria-labelledby.&#x22; },
  className: { type: &#x22;string | ((state: ListBoxRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ListBox`](https://react-aria.adobe.com/ListBox#api).

### ListBoxItem

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Set automatically from item.id with dynamic items.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Plain text for typeahead. Defaults to children when they're a string.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this item.&#x22; },
  value: { type: &#x22;T&#x22;, description: &#x22;The item object, when using dynamic collections.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Renders the item as a link.&#x22; },
  target: { type: &#x22;string&#x22;, description: &#x22;Link target, e.g. _blank.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when this item is actioned.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when children aren't text.&#x22; },
  className: { type: &#x22;string | ((state: ListBoxItemRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: ListBoxItemRenderProps) => ReactNode)&#x22; },
}"
/>

### ListBoxSection

<TypeTable
  type="{
  title: { type: &#x22;string&#x22;, description: &#x22;Heading shown above the group; also its accessible name.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22; },
  id: { type: &#x22;Key&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there's no title.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

### ListBoxItemLabel / ListBoxItemDescription

Accept every prop of React Aria's [`Text`](https://react-aria.adobe.com/ListBox#text-slots). They set `slot="label"` and `slot="description"`.

## Related

* [Select](/docs/components/select) — this list in a popover, for one value in a form.
* [Combo Box](/docs/components/combobox) — a searchable select.
* [Grid List](/docs/components/grid-list) — interactive rows with actions and checkboxes.
* [Tag Group](/docs/components/tag-group) — compact, removable selections.

---

# Grid List

Source: https://desyne.dev/docs/components/grid-list

> An interactive list whose rows can hold buttons, menus and links. Supports single and multiple selection with checkboxes, row actions, links, drag-to-reorder and drag between lists, card grid layouts, infinite loading and empty states.

```tsx title="grid-list/demo.tsx"
"use client";

import { FileTextIcon, ImageIcon, SheetIcon } from "lucide-react";
import {
  GridList,
  GridListItem,
  GridListItemDescription,
  GridListItemLabel,
} from "@/components/ui/grid-list";

const files = [
  {
    id: "1",
    name: "Q3 report.pdf",
    meta: "2.4 MB · Edited 2h ago",
    icon: FileTextIcon,
  },
  {
    id: "2",
    name: "Budget 2027.xlsx",
    meta: "860 KB · Edited yesterday",
    icon: SheetIcon,
  },
  {
    id: "3",
    name: "Hero banner.png",
    meta: "1.1 MB · Edited Sep 12",
    icon: ImageIcon,
  },
];

export default function GridListDemo() {
  return (
    <GridList
      aria-label="Files"
      items={files}
      selectionMode="multiple"
      className="w-80"
    >
      {(file) => (
        <GridListItem textValue={file.name}>
          <span className="flex size-8 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
            <file.icon className="size-4" />
          </span>
          <span className="flex min-w-0 flex-col">
            <GridListItemLabel>{file.name}</GridListItemLabel>
            <GridListItemDescription>{file.meta}</GridListItemDescription>
          </span>
        </GridListItem>
      )}
    </GridList>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/grid-list
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  GridList,
  GridListItem,
  GridListItemDescription,
  GridListItemLabel,
} from "@/components/ui/grid-list";
```

```tsx
<GridList aria-label="Files" selectionMode="multiple">
  <GridListItem id="report">Q3 report.pdf</GridListItem>
  <GridListItem id="budget">Budget 2027.xlsx</GridListItem>
</GridList>
```

<Callout title="Rows can contain controls">
  Unlike [List Box](/docs/components/list-box), grid list rows are `role="row"`
  and may contain buttons, menus, switches and links. Arrow keys move between
  rows, and <kbd>←</kbd> / <kbd>→</kbd> move into a row's controls. Selection
  checkboxes and drag handles are added for you.
</Callout>

### When to use

* Grid List — a list of objects users act on: files, members, notifications, tasks, cards.
* [List Box](/docs/components/list-box) — choosing values from plain options, with no controls inside rows.
* [Table](/docs/components/table) — multiple columns of comparable data, sorting and column headers.
* [Menu](/docs/components/menu) — a transient list of commands.

## Anatomy

```tsx
<GridList>                         {/* role="grid" */}
  <GridListItem>                   {/* role="row" */}
    {/* drag handle, when dragAndDropHooks is set */}
    {/* selection checkbox, when selectionMode is set */}
    <Icon />
    <GridListItemLabel />
    <GridListItemDescription />
    <Button />                     {/* any interactive content */}
  </GridListItem>
</GridList>
```

| Part                      | Renders                                      | Notes                                                                                   |
| ------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------- |
| `GridList`                | `<div role="grid">`                          | Scrollable list. `variant` sets the frame. Shows `renderEmptyState` when empty.         |
| `GridListItem`            | `<div role="row">` › `<div role="gridcell">` | A row. Plain-string children become its `textValue`.                                    |
| Drag handle               | `<button slot="drag">`                       | Grip icon, rendered automatically when the list has `dragAndDropHooks`.                 |
| Selection checkbox        | [`Checkbox`](/docs/components/checkbox)      | Rendered automatically when `selectionMode` is set and `selectionBehavior` is `toggle`. |
| `GridListItemLabel`       | `<span>`                                     | Bold, truncated primary text.                                                           |
| `GridListItemDescription` | `<span slot="description">`                  | Muted secondary text, linked as the row's description.                                  |

## Examples

### Variants

`bordered` (default) frames the list as a card, `separated` draws a divider between rows, and `plain` has no frame for embedding in your own container.

Example `grid-list/variants`: source in https://desyne.dev/docs/components/grid-list.md

### Single selection

`selectionMode="single"` adds a checkbox that behaves like a radio. `disallowEmptySelection` keeps one row selected.

Example `grid-list/single-selection`: source in https://desyne.dev/docs/components/grid-list.md

### Controlled selection

`selectedKeys` and `onSelectionChange` own the selection. Handle both a `Set` of keys and `"all"` (after <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>A</kbd> or the select-all shortcut).

Example `grid-list/controlled`: source in https://desyne.dev/docs/components/grid-list.md

### Selection behavior

`selectionBehavior="replace"` hides the checkboxes and selects like a file browser: a click selects one row, <kbd>⌘</kbd>/<kbd>Ctrl</kbd> or <kbd>Shift</kbd> add more.

Example `grid-list/selection-behavior`: source in https://desyne.dev/docs/components/grid-list.md

### Disabled rows

`disabledKeys` disables rows. With `disabledBehavior="selection"` they can't be selected but stay focusable, so keyboard and screen reader users can still reach them and their contents. The default `all` disables every interaction.

Example `grid-list/disabled`: source in https://desyne.dev/docs/components/grid-list.md

### Row actions and controls

`onAction` fires when a row is clicked or <kbd>Enter</kbd> is pressed. Buttons and [menus](/docs/components/menu) inside the row handle their own presses without triggering the row action.

Example `grid-list/actions`: source in https://desyne.dev/docs/components/grid-list.md

### Links

Give rows an `href` to make the whole row a link. They work with client-side routers through React Aria's `RouterProvider`.

Example `grid-list/links`: source in https://desyne.dev/docs/components/grid-list.md

### Empty state

`renderEmptyState` renders when there are no items. The list gets `data-empty` and centered, muted text.

Example `grid-list/empty`: source in https://desyne.dev/docs/components/grid-list.md

### Drag to reorder

Pass `dragAndDropHooks` from `useDragAndDrop` and each row gets a drag handle. Update your data in `onReorder`, and use `renderDropIndicator` with React Aria's `DropIndicator` to show where items will land. Keyboard users focus the handle and press <kbd>Enter</kbd> to start dragging.

Example `grid-list/reorder`: source in https://desyne.dev/docs/components/grid-list.md

### Grid layout

`layout="grid"` enables two-dimensional arrow key navigation. Combine it with `variant="plain"` and CSS grid classes to build a card picker; restyle rows with `className`.

Example `grid-list/grid-layout`: source in https://desyne.dev/docs/components/grid-list.md

### Infinite loading

Render the items in a `Collection` followed by `GridListLoadMoreItem`, which calls `onLoadMore` as it scrolls into view. `useAsyncList` handles cursors and loading state. Give the list a fixed height.

Example `grid-list/async`: source in https://desyne.dev/docs/components/grid-list.md

## Recipes

### File manager with bulk actions

A plain grid list inside a card, with a toolbar that switches to bulk actions while rows are selected.

Example `grid-list/recipe-file-manager`: source in https://desyne.dev/docs/components/grid-list.md

### Kanban board

Three lists that share a custom drag type. `onInsert` and `onRootDrop` accept items from other columns, `onReorder` moves within a column, and `onDragEnd` removes moved items from the source.

Example `grid-list/recipe-kanban`: source in https://desyne.dev/docs/components/grid-list.md

### Notification inbox

A `separated` list where `onAction` marks a notification as read. The unread dot has visually hidden text so it's announced.

Example `grid-list/recipe-notifications`: source in https://desyne.dev/docs/components/grid-list.md

## Accessibility

* The list is `role="grid"` and each item is a `role="row"` with a single `gridcell`, so screen readers announce row position and selection.
* Always provide `aria-label` or `aria-labelledby`.
* Focus is a single tab stop with arrow key navigation between rows. Interactive children are reached with <kbd>←</kbd> / <kbd>→</kbd> (or <kbd>Tab</kbd> with `keyboardNavigationBehavior="tab"`).
* Give icon-only buttons inside rows an `aria-label`, and make sure row text is available as `textValue` for typeahead and announcements.
* Selection checkboxes are labelled from the row automatically.
* Drag and drop has built-in keyboard and screen reader support, with live announcements for each step.

### Keyboard

| Key                                                           | Action                                                                  |
| ------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <kbd>Tab</kbd>                                                | Moves focus into and out of the list                                    |
| <kbd>↑</kbd> / <kbd>↓</kbd>                                   | Moves focus to the previous / next row (all four arrows in grid layout) |
| <kbd>←</kbd> / <kbd>→</kbd>                                   | Moves focus between the row and its interactive children                |
| <kbd>Home</kbd> / <kbd>End</kbd>                              | Moves focus to the first / last row                                     |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                     | Moves focus by a page                                                   |
| <kbd>Space</kbd>                                              | Toggles selection of the focused row                                    |
| <kbd>Enter</kbd>                                              | Triggers `onAction`, follows a link, or starts a drag from the handle   |
| <kbd>Shift</kbd>+<kbd>↑</kbd> / <kbd>Shift</kbd>+<kbd>↓</kbd> | Extends the selection (multiple)                                        |
| <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>A</kbd>                     | Selects all (multiple)                                                  |
| <kbd>Esc</kbd>                                                | Clears the selection, or cancels a drag                                 |
| Any character                                                 | Typeahead (unless `disallowTypeAhead`)                                  |

## Styling

### Data attributes

On the `GridList` (use `group-data-*/list:` inside it):

| Attribute                             | Present when                               |
| ------------------------------------- | ------------------------------------------ |
| `data-variant`                        | Always: `bordered`, `separated` or `plain` |
| `data-empty`                          | There are no items                         |
| `data-focused` / `data-focus-visible` | The list itself has focus / keyboard focus |
| `data-drop-target`                    | Something is being dragged over the list   |
| `data-layout`                         | Always: `stack` or `grid`                  |
| `data-orientation`                    | Always: `vertical` or `horizontal`         |

On each `GridListItem` (use `group-data-*/item:` inside it):

| Attribute                                | Present when                                        |
| ---------------------------------------- | --------------------------------------------------- |
| `data-selected`                          | The row is selected                                 |
| `data-focused` / `data-focus-visible`    | The row has focus / keyboard focus                  |
| `data-focus-visible-within`              | A control inside the row has keyboard focus         |
| `data-hovered` / `data-pressed`          | Hovered with a mouse / being pressed                |
| `data-disabled`                          | The row is disabled                                 |
| `data-selection-mode`                    | `single` or `multiple`                              |
| `data-allows-dragging` / `data-dragging` | Drag and drop is enabled / the row is being dragged |
| `data-drop-target`                       | The row is the current drop target                  |

### Slots

| `data-slot`            | Element             |
| ---------------------- | ------------------- |
| `grid-list`            | Root                |
| `grid-list-item`       | Each row            |
| `grid-list-item-label` | `GridListItemLabel` |

* The list has `max-h-[inherit]` and `overflow-auto`; give it a `max-h-*` or `h-*` to scroll.
* Rows are `flex items-center gap-3`, so icons, text and trailing controls line up without extra wrappers. Give the text block `flex-1` to push controls to the end.
* `className` on `GridList` and `GridListItem` also accepts a function of the render props, e.g. `({ isSelected }) => …`.

## API Reference

### GridList

<TypeTable
  type="{
  variant: { type: '&#x22;bordered&#x22; | &#x22;separated&#x22; | &#x22;plain&#x22;', default: '&#x22;bordered&#x22;', description: &#x22;Frame around the list.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static rows, or a render function.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;none&#x22;' },
  selectionBehavior: { type: '&#x22;toggle&#x22; | &#x22;replace&#x22;', default: '&#x22;toggle&#x22;', description: &#x22;toggle shows checkboxes; replace selects like a file browser.&#x22; },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Prevents deselecting the last row.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Rows that are disabled.&#x22; },
  disabledBehavior: { type: '&#x22;all&#x22; | &#x22;selection&#x22;', default: '&#x22;all&#x22;', description: &#x22;Whether disabled rows block all interaction, or only selection.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when a row is actioned (click or Enter).&#x22; },
  renderEmptyState: { type: &#x22;(props: GridListRenderProps) => ReactNode&#x22;, description: &#x22;Content shown when there are no items.&#x22; },
  dragAndDropHooks: { type: &#x22;DragAndDropHooks&#x22;, description: &#x22;From useDragAndDrop. Adds drag handles to rows.&#x22; },
  layout: { type: '&#x22;stack&#x22; | &#x22;grid&#x22;', default: '&#x22;stack&#x22;', description: &#x22;grid enables two-dimensional keyboard navigation.&#x22; },
  orientation: { type: '&#x22;vertical&#x22; | &#x22;horizontal&#x22;', default: '&#x22;vertical&#x22;' },
  keyboardNavigationBehavior: { type: '&#x22;arrow&#x22; | &#x22;tab&#x22;', default: '&#x22;arrow&#x22;', description: &#x22;How focus moves to controls inside rows.&#x22; },
  disallowTypeAhead: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  escapeKeyBehavior: { type: '&#x22;clearSelection&#x22; | &#x22;none&#x22;', default: '&#x22;clearSelection&#x22;' },
  shouldSelectOnPressUp: { type: &#x22;boolean&#x22;, description: &#x22;Selects on pointer up instead of down.&#x22; },
  autoFocus: { type: 'boolean | &#x22;first&#x22; | &#x22;last&#x22;', description: &#x22;Focuses the list, or its first / last row, on mount.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that invalidate cached row rendering.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required unless you pass aria-labelledby.&#x22; },
  className: { type: &#x22;string | ((state: GridListRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`GridList`](https://react-aria.adobe.com/GridList#api).

### GridListItem

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Set automatically from item.id with dynamic items.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Plain text for typeahead and announcements. Defaults to children when they're a string.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this row.&#x22; },
  value: { type: &#x22;T&#x22;, description: &#x22;The item object, when using dynamic collections.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Makes the row a link.&#x22; },
  target: { type: &#x22;string&#x22;, description: &#x22;Link target, e.g. _blank.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when this row is actioned.&#x22; },
  focusMode: { type: '&#x22;row&#x22; | &#x22;child&#x22;', default: '&#x22;row&#x22;', description: &#x22;Focus the row, or its first focusable child, when navigating.&#x22; },
  allowsArrowNavigation: { type: &#x22;boolean&#x22;, description: &#x22;Keep arrow key navigation between rows when a child control has focus (tab mode).&#x22; },
  className: { type: &#x22;string | ((state: GridListItemRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: GridListItemRenderProps) => ReactNode)&#x22; },
}"
/>

### GridListItemLabel

Accepts every prop of `<span>`.

### GridListItemDescription

Accepts every prop of React Aria's `Text`. It sets `slot="description"`.

## Related

* [List Box](/docs/components/list-box) — selectable options without interactive content.
* [Table](/docs/components/table) — rows and columns with sorting.
* [Menu](/docs/components/menu) — for per-row action menus.
* [Checkbox](/docs/components/checkbox) — the selection control used in rows.

---

# Table

Source: https://desyne.dev/docs/components/table

> An accessible data table with row selection and automatic checkbox column, sortable columns, row actions and links, dynamic columns, drag-to-reorder, empty states, and three densities with optional striping, grid lines and frame.

```tsx title="table/demo.tsx"
"use client";

import { Badge } from "@/components/ui/badge";
import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader,
} from "@/components/ui/table";

const invoices = [
  {
    id: "INV-1042",
    customer: "Acme Corp",
    status: "Paid",
    amount: "$2,500.00",
  },
  {
    id: "INV-1043",
    customer: "Globex",
    status: "Pending",
    amount: "$1,150.00",
  },
  {
    id: "INV-1044",
    customer: "Initech",
    status: "Overdue",
    amount: "$3,420.00",
  },
  { id: "INV-1045", customer: "Umbrella", status: "Paid", amount: "$980.00" },
];

const tone = {
  Paid: "success",
  Pending: "warning",
  Overdue: "danger",
} as const;

export default function TableDemo() {
  return (
    <Table aria-label="Invoices" className="min-w-[480px]">
      <TableHeader>
        <Column isRowHeader>Invoice</Column>
        <Column>Customer</Column>
        <Column>Status</Column>
        <Column className="text-right">Amount</Column>
      </TableHeader>
      <TableBody items={invoices}>
        {(invoice) => (
          <Row>
            <Cell className="font-medium">{invoice.id}</Cell>
            <Cell>{invoice.customer}</Cell>
            <Cell>
              <Badge
                variant="dot"
                color={tone[invoice.status as keyof typeof tone]}
              >
                {invoice.status}
              </Badge>
            </Cell>
            <Cell className="text-right tabular-nums">{invoice.amount}</Cell>
          </Row>
        )}
      </TableBody>
    </Table>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/table
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader,
} from "@/components/ui/table";
```

```tsx
<Table aria-label="Users">
  <TableHeader>
    <Column isRowHeader>Name</Column>
    <Column>Role</Column>
  </TableHeader>
  <TableBody items={users}>
    {(user) => (
      <Row>
        <Cell>{user.name}</Cell>
        <Cell>{user.role}</Cell>
      </Row>
    )}
  </TableBody>
</Table>
```

<Callout title="Mark a row header">
  Set `isRowHeader` on the column that identifies each row (usually a name or
  id). Screen readers read it when moving between rows, so users know which
  row they're in. Every item in `items` also needs a unique `id`.
</Callout>

### When to use

* Table — comparing records across several attributes, with sorting, selection or bulk actions.
* [Grid List](/docs/components/grid-list) — a single column of rich rows, cards, or mobile-first lists.
* [List Box](/docs/components/list-box) — picking values, not browsing data.
* For simple, non-interactive tabular content in prose, a plain HTML `<table>` is fine.

## Anatomy

```tsx
<Table>                     {/* scroll container + role="grid" */}
  <TableHeader>             {/* adds a select-all column when selecting */}
    <Column isRowHeader />
    <Column allowsSorting />
  </TableHeader>
  <TableBody>
    <Row>                   {/* adds a checkbox cell when selecting */}
      <Cell />
      <Cell />
    </Row>
  </TableBody>
</Table>
```

| Part          | Renders                         | Notes                                                                                                                           |
| ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `Table`       | `<div>` › `<table role="grid">` | The `div` scrolls horizontally and draws the card frame (`framed`). Provides `density`, `striped` and `bordered` to every cell. |
| `TableHeader` | `<thead>`                       | Muted background. Adds a checkbox column (select all in `multiple` mode) when `selectionBehavior` is `toggle`.                  |
| `Column`      | `<th role="columnheader">`      | Small, muted, non-wrapping. Shows a sort arrow when `allowsSorting`.                                                            |
| `TableBody`   | `<tbody>`                       | Rows, or `renderEmptyState` when there are none.                                                                                |
| `Row`         | `<tr role="row">`               | Hover and selected backgrounds. Adds a checkbox cell when selection uses checkboxes.                                            |
| `Cell`        | `<td role="gridcell">`          | Non-wrapping, padded by `density`.                                                                                              |

## Examples

### Density, striped and bordered

`density` sets cell padding (`compact`, `default`, `comfortable`). `striped` shades every other row, and `bordered` adds vertical grid lines.

Example `table/density`: source in https://desyne.dev/docs/components/table.md

### Without a frame

`framed={false}` drops the table's own border and shadow so it can sit inside a card or panel.

Example `table/framed`: source in https://desyne.dev/docs/components/table.md

### Single selection

`selectionMode="single"` adds a checkbox column without a select-all box. Combine with `disallowEmptySelection` for a required choice.

Example `table/single-selection`: source in https://desyne.dev/docs/components/table.md

### Multiple selection and sorting

`selectionMode="multiple"` adds a select-all checkbox to the header. Sorting is controlled: give sortable columns an `id` and `allowsSorting`, then sort your data in `onSortChange`.

Example `table/selection-sorting`: source in https://desyne.dev/docs/components/table.md

### Sorting

Clicking a sortable header (or pressing <kbd>Enter</kbd> on it) toggles ascending and descending. The table only reports the new `SortDescriptor`; compare numbers numerically and strings with `localeCompare` (or `Intl.Collator`) yourself.

Example `table/sorting`: source in https://desyne.dev/docs/components/table.md

### Selection behavior

`selectionBehavior="replace"` removes the checkbox column. A click selects one row, <kbd>⌘</kbd>/<kbd>Ctrl</kbd> and <kbd>Shift</kbd> add more, and arrow keys move the selection like a desktop mail client.

Example `table/selection-behavior`: source in https://desyne.dev/docs/components/table.md

### Disabled rows

`disabledKeys` prevents selecting (and by default focusing) rows. Style them with `data-disabled:` on `Row`. `disabledBehavior="selection"` keeps them focusable.

Example `table/disabled`: source in https://desyne.dev/docs/components/table.md

### Row actions

`onRowAction` makes rows actionable: clicking a row or pressing <kbd>Enter</kbd> calls it with the row's key. With checkbox selection as well, clicking a row performs the action while nothing is selected, and toggles selection once rows are selected; use `selectionBehavior="replace"` to select on click and act on double click or <kbd>Enter</kbd>.

Example `table/row-actions`: source in https://desyne.dev/docs/components/table.md

### Links

Give a `Row` an `href` and the whole row navigates. Works with client-side routers through React Aria's `RouterProvider`.

Example `table/links`: source in https://desyne.dev/docs/components/table.md

### Dynamic columns

Pass `columns` to `TableHeader` and each `Row`, and render both with functions. Here a multi-select [`Menu`](/docs/components/menu) toggles column visibility; `dependencies` on `TableBody` re-renders rows when the columns change.

Example `table/dynamic-columns`: source in https://desyne.dev/docs/components/table.md

### Rich cells

Cells take any content: [avatars](/docs/components/avatar), [badges](/docs/components/badge), progress bars. Right-align numbers with `text-right tabular-nums` on both the column and its cells.

Example `table/rich-cells`: source in https://desyne.dev/docs/components/table.md

### Empty state

`renderEmptyState` on `TableBody` fills the body when there are no rows.

Example `table/empty`: source in https://desyne.dev/docs/components/table.md

### Drag to reorder

Pass `dragAndDropHooks` from `useDragAndDrop`, add a column for the handle, and render a React Aria `Button` with `slot="drag"` in its cell. Rows can then be reordered by mouse, touch or keyboard.

Example `table/reorder`: source in https://desyne.dev/docs/components/table.md

### Without grid lines

`divided={false}` removes the lines between rows. Pair it with `striped` (or nothing at all) for light, list-like tables such as plan comparisons.

Example `table/gridless`: source in https://desyne.dev/docs/components/table.md

### Bleed

`bleed` drops the frame and lets the table run into its parent's horizontal padding (`-mx-4`, `sm:-mx-6`), so row hovers and dividers reach the card's edges while the first and last columns stay aligned with the text around them. Use it inside cards and sheets that use `px-4 sm:px-6`.

Example `table/bleed`: source in https://desyne.dev/docs/components/table.md

### Expandable rows

Keep a set of expanded ids, put a `TableExpandButton` in the first cell and render the detail as an extra `Row` right after the parent, with one `Cell` that spans every column (`colSpan`). The button sets `aria-expanded`, and the detail row stays in the grid, so keyboard users reach it with the arrow keys.

Example `table/expandable`: source in https://desyne.dev/docs/components/table.md

### Infinite scrolling

Give the table a fixed-height scroll container with `containerClassName` (the header stays sticky) and add `TableLoadMore` as the last child of `TableBody`. It calls `onLoadMore` when it scrolls into view and shows a spinner row while `isLoading` is true. Remove it, or stop calling your loader, when there's nothing left to fetch.

Example `table/infinite`: source in https://desyne.dev/docs/components/table.md

### Resizable columns

Set `allowsResizing` on `Table` to let people drag column edges. Each `Column` gets a resize handle; give columns a `defaultWidth` (pixels, `%` or `fr`) and a `minWidth`/`maxWidth` to shape the starting layout, and opt one out with `isResizable={false}`. Keyboard users focus a header, press Enter to enter resize mode and use the arrow keys. `onResizeEnd` receives every column's width, which is the place to persist a user's layout. Cells truncate with an ellipsis while the table is resizable.

Example `table/resizable`: source in https://desyne.dev/docs/components/table.md

## Recipes

### Data table

Search, a status filter, sortable columns, a bulk-action bar that replaces the toolbar while rows are selected, and client-side pagination with [`Paginator`](/docs/components/pagination).

Example `table/recipe-data-table`: source in https://desyne.dev/docs/components/table.md

### Member management

An inline role [`Select`](/docs/components/select) and a per-row action [`Menu`](/docs/components/menu). Controls inside cells are reachable with the arrow keys and labelled with the member's name.

Example `table/recipe-row-actions`: source in https://desyne.dev/docs/components/table.md

### Permission matrix

A [`Checkbox`](/docs/components/checkbox) in every cell, `bordered` grid lines and compact density. Each checkbox's `aria-label` names both the permission and the role.

Example `table/recipe-permissions`: source in https://desyne.dev/docs/components/table.md

## Accessibility

* The table is a `role="grid"`: users move between cells with the arrow keys, and focus is a single tab stop.
* Label the table with `aria-label` or `aria-labelledby`, and mark one column `isRowHeader`.
* Sortable columns announce their sort direction with `aria-sort`.
* The selection checkboxes are labelled automatically ("Select", "Select all") and linked to the row header.
* Controls inside cells (buttons, selects, checkboxes) are reachable by arrowing into the cell. Give icon-only buttons an `aria-label` that names the row.
* Visually hidden column labels (like "Actions") keep header cells meaningful for screen readers.
* Drag and drop has keyboard and screen reader support built in.

### Keyboard

| Key                                                              | Action                                                          |
| ---------------------------------------------------------------- | --------------------------------------------------------------- |
| <kbd>Tab</kbd>                                                   | Moves focus into and out of the table                           |
| <kbd>↑</kbd> / <kbd>↓</kbd>                                      | Moves focus to the row or cell above / below                    |
| <kbd>←</kbd> / <kbd>→</kbd>                                      | Moves focus between cells in a row (and into a cell's controls) |
| <kbd>Home</kbd> / <kbd>End</kbd>                                 | Moves focus to the first / last cell in the row                 |
| <kbd>Ctrl</kbd>+<kbd>Home</kbd> / <kbd>Ctrl</kbd>+<kbd>End</kbd> | Moves focus to the first / last row                             |
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd>                        | Moves focus by a page                                           |
| <kbd>Space</kbd>                                                 | Toggles selection of the focused row                            |
| <kbd>Enter</kbd>                                                 | Sorts by the focused column, or triggers the row action / link  |
| <kbd>Shift</kbd>+<kbd>↑</kbd> / <kbd>Shift</kbd>+<kbd>↓</kbd>    | Extends the selection (multiple)                                |
| <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>A</kbd>                        | Selects all rows (multiple)                                     |
| <kbd>Esc</kbd>                                                   | Clears the selection                                            |

## Styling

### Data attributes

| Attribute                                | On                                     | Present when                                           |
| ---------------------------------------- | -------------------------------------- | ------------------------------------------------------ |
| `data-focused` / `data-focus-visible`    | `Table`, `Column`, `Row`, `Cell`       | Focused / keyboard focused                             |
| `data-drop-target`                       | `Table`, `TableBody`, `Row`            | A drag is over it                                      |
| `data-hovered`                           | `TableHeader`, `Column`, `Row`, `Cell` | Hovered with a mouse                                   |
| `data-pressed`                           | `Column`, `Row`, `Cell`                | Being pressed                                          |
| `data-allows-sorting`                    | `Column`                               | `allowsSorting` is set                                 |
| `data-sort-direction`                    | `Column`                               | `ascending` or `descending` when sorted by this column |
| `data-empty`                             | `TableBody`                            | There are no rows                                      |
| `data-selected`                          | `Row`, `Cell`                          | The row is selected                                    |
| `data-disabled`                          | `Row`, `Cell`                          | The row is disabled                                    |
| `data-selection-mode`                    | `Row`                                  | `single` or `multiple`                                 |
| `data-focus-visible-within`              | `Row`                                  | A cell or control in the row has keyboard focus        |
| `data-dragging` / `data-allows-dragging` | `Row`                                  | The row is being dragged / drag and drop is enabled    |

`Column` and `Row` are Tailwind groups (`group/column`, `group/row`), so children can use `group-data-selected/row:` or `group-data-hovered/column:`.

### Slots

| `data-slot`                               | Element                     |
| ----------------------------------------- | --------------------------- |
| `table-container`                         | Scroll container and frame  |
| `table`                                   | `<table>`                   |
| `table-header` / `table-column`           | Header row and header cells |
| `table-body` / `table-row` / `table-cell` | Body, rows and cells        |

### Customizing

* `className` on `Table` styles the `<table>` element (for example `min-w-[640px]` to force horizontal scroll). The container is always `w-full overflow-auto`.
* Cells don't wrap by default. Add `whitespace-normal` to a `Cell` for long text, or `max-w-* truncate` to clip it.
* Set column widths with `w-*` classes on `Column`.
* Every part's `className` also accepts a function of its render props.
* Column resizing and expandable tree rows aren't part of this component.

## API Reference

### Table

<TypeTable
  type="{
  density: { type: '&#x22;compact&#x22; | &#x22;default&#x22; | &#x22;comfortable&#x22;', default: '&#x22;default&#x22;', description: &#x22;Cell padding.&#x22; },
  striped: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shades every other row.&#x22; },
  bordered: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Vertical grid lines between cells.&#x22; },
  framed: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Rounded, bordered card around the table.&#x22; },
  divided: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Lines between rows. false gives a gridless table.&#x22; },
  bleed: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;No frame; extends into the parent's horizontal padding with edge cells aligned to the content.&#x22; },
  containerClassName: { type: &#x22;string&#x22;, description: &#x22;Classes for the scroll container, e.g. max-h-80 for infinite scrolling.&#x22; },
  allowsResizing: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Wraps the table in a ResizableTableContainer and adds a resize handle to every column.&#x22; },
  onResize: { type: &#x22;(widths: Map<Key, ColumnSize>) => void&#x22;, description: &#x22;Called while a column is being resized.&#x22; },
  onResizeEnd: { type: &#x22;(widths: Map<Key, ColumnSize>) => void&#x22;, description: &#x22;Called when a resize ends. Persist widths here.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;none&#x22;' },
  selectionBehavior: { type: '&#x22;toggle&#x22; | &#x22;replace&#x22;', default: '&#x22;toggle&#x22;', description: &#x22;toggle adds a checkbox column; replace selects rows on click.&#x22; },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Rows that are disabled.&#x22; },
  disabledBehavior: { type: '&#x22;all&#x22; | &#x22;selection&#x22;', default: '&#x22;all&#x22;', description: &#x22;Whether disabled rows block all interaction, or only selection.&#x22; },
  sortDescriptor: { type: &#x22;SortDescriptor&#x22;, description: &#x22;Controlled sort: { column, direction }.&#x22; },
  onSortChange: { type: &#x22;(descriptor: SortDescriptor) => void&#x22;, description: &#x22;Called when a sortable column header is pressed.&#x22; },
  onRowAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when a row is actioned.&#x22; },
  dragAndDropHooks: { type: &#x22;DragAndDropHooks&#x22;, description: &#x22;From useDragAndDrop.&#x22; },
  keyboardNavigationBehavior: { type: '&#x22;arrow&#x22; | &#x22;tab&#x22;', default: '&#x22;arrow&#x22;', description: &#x22;How focus moves to controls inside cells.&#x22; },
  escapeKeyBehavior: { type: '&#x22;clearSelection&#x22; | &#x22;none&#x22;', default: '&#x22;clearSelection&#x22;' },
  shouldSelectOnPressUp: { type: &#x22;boolean&#x22;, description: &#x22;Selects on pointer up instead of down.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required unless you pass aria-labelledby.&#x22; },
  className: { type: &#x22;string | ((state: TableRenderProps) => string)&#x22;, description: &#x22;Classes for the <table> element.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Table`](https://react-aria.adobe.com/Table#api).

### TableHeader

<TypeTable
  type="{
  columns: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Column objects for dynamic rendering.&#x22; },
  children: { type: &#x22;ReactNode | ((column: T) => ReactElement)&#x22;, description: &#x22;Static Columns, or a render function.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that invalidate cached columns.&#x22; },
  className: { type: &#x22;string | ((state: TableHeaderRenderProps) => string)&#x22; },
}"
/>

### Column

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Identifies the column in sortDescriptor and dynamic rows.&#x22; },
  isRowHeader: { type: &#x22;boolean&#x22;, description: &#x22;Announces this column's cell when navigating rows.&#x22; },
  allowsSorting: { type: &#x22;boolean&#x22;, description: &#x22;Makes the header sortable and shows the sort arrow.&#x22; },
  isResizable: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Inside a table with allowsResizing, set false to hide this column's resize handle.&#x22; },
  defaultWidth: { type: &#x22;ColumnSize&#x22;, description: &#x22;Starting width: pixels, a percentage or a fraction like \&#x22;2fr\&#x22;.&#x22; },
  width: { type: &#x22;ColumnSize&#x22;, description: &#x22;Controlled width.&#x22; },
  minWidth: { type: &#x22;number | string&#x22;, description: &#x22;Smallest width the column can be resized to.&#x22; },
  maxWidth: { type: &#x22;number | string&#x22;, description: &#x22;Largest width the column can be resized to.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Accessible text when children aren't a string.&#x22; },
  focusMode: { type: '&#x22;child&#x22; | &#x22;cell&#x22;', description: &#x22;Focus the header, or its first focusable child.&#x22; },
  className: { type: &#x22;string | ((state: ColumnRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: ColumnRenderProps) => ReactNode)&#x22; },
}"
/>

### TableLoadMore

<TypeTable
  type="{
  onLoadMore: { type: &#x22;() => void&#x22;, description: &#x22;Called when the row scrolls into view.&#x22; },
  isLoading: { type: &#x22;boolean&#x22;, description: &#x22;Shows the spinner row while true.&#x22; },
  scrollOffset: { type: &#x22;number&#x22;, default: &#x22;1&#x22;, description: &#x22;How many viewport heights early to trigger onLoadMore.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Replaces the default spinner and label.&#x22; },
}"
/>

### TableExpandButton

<TypeTable
  type="{
  isExpanded: { type: &#x22;boolean&#x22;, description: &#x22;Rotates the chevron and sets aria-expanded.&#x22; },
  onPress: { type: &#x22;(e: PressEvent) => void&#x22;, description: &#x22;Toggle your expanded state here.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, default: '&#x22;Expand row&#x22;', description: &#x22;Name the row it controls, e.g. \&#x22;Show items in ORD-4821\&#x22;.&#x22; },
}"
/>

### TableBody

<TypeTable
  type="{
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Row objects for dynamic rendering.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactElement)&#x22;, description: &#x22;Static Rows, or a render function.&#x22; },
  renderEmptyState: { type: &#x22;(props: TableBodyRenderProps) => ReactNode&#x22;, description: &#x22;Content shown when there are no rows.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that invalidate cached rows.&#x22; },
  className: { type: &#x22;string | ((state: TableBodyRenderProps) => string)&#x22; },
}"
/>

### Row

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Set automatically from item.id with dynamic items.&#x22; },
  columns: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Columns for rendering cells with a function.&#x22; },
  children: { type: &#x22;ReactNode | ((column: T) => ReactElement)&#x22;, description: &#x22;Cells, or a render function per column.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Text for typeahead.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this row.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Makes the row a link.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when this row is actioned.&#x22; },
  dependencies: { type: &#x22;ReadonlyArray<any>&#x22;, description: &#x22;Values that invalidate cached cells.&#x22; },
  className: { type: &#x22;string | ((state: RowRenderProps) => string)&#x22; },
}"
/>

### Cell

<TypeTable
  type="{
  textValue: { type: &#x22;string&#x22;, description: &#x22;Accessible text when children aren't a string.&#x22; },
  colSpan: { type: &#x22;number&#x22;, description: &#x22;Number of columns the cell spans.&#x22; },
  focusMode: { type: '&#x22;child&#x22; | &#x22;cell&#x22;', description: &#x22;Focus the cell, or its first focusable child.&#x22; },
  className: { type: &#x22;string | ((state: CellRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: CellRenderProps) => ReactNode)&#x22; },
}"
/>

## Related

* [Grid List](/docs/components/grid-list) — single-column interactive lists and cards.
* [Pagination](/docs/components/pagination) — page controls for long tables.
* [Menu](/docs/components/menu) — row action menus and column pickers.
* [Checkbox](/docs/components/checkbox) — the selection control used in rows.

---

# Tree

Source: https://desyne.dev/docs/components/tree

> An expandable hierarchy such as a file explorer, docs navigation or nested permissions. Items take a title, an icon that can follow the expanded state and a trailing suffix, with single or multiple selection and full keyboard support.

```tsx title="tree/demo.tsx"
"use client";

import {
  FileCodeIcon,
  FileJsonIcon,
  FileTextIcon,
  FolderIcon,
  FolderOpenIcon,
} from "lucide-react";
import { Tree, TreeItem } from "@/components/ui/tree";

const folder = ({ isExpanded }: { isExpanded: boolean }) =>
  isExpanded ? <FolderOpenIcon /> : <FolderIcon />;

export default function TreeDemo() {
  return (
    <Tree
      aria-label="Project files"
      variant="bordered"
      defaultExpandedKeys={["app", "components"]}
      className="w-72"
    >
      <TreeItem id="app" title="app" icon={folder}>
        <TreeItem id="layout" title="layout.tsx" icon={<FileCodeIcon />} />
        <TreeItem id="page" title="page.tsx" icon={<FileCodeIcon />} />
        <TreeItem id="settings" title="settings" icon={folder}>
          <TreeItem
            id="settings-page"
            title="page.tsx"
            textValue="settings/page.tsx"
            icon={<FileCodeIcon />}
          />
        </TreeItem>
      </TreeItem>
      <TreeItem id="components" title="components" icon={folder}>
        <TreeItem id="ui" title="ui" icon={folder}>
          <TreeItem id="button" title="button.tsx" icon={<FileCodeIcon />} />
          <TreeItem id="tree" title="tree.tsx" icon={<FileCodeIcon />} />
        </TreeItem>
        <TreeItem id="header" title="site-header.tsx" icon={<FileCodeIcon />} />
      </TreeItem>
      <TreeItem id="package" title="package.json" icon={<FileJsonIcon />} />
      <TreeItem id="readme" title="README.md" icon={<FileTextIcon />} />
    </Tree>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/tree
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components.

## Usage

```tsx
import { Tree, TreeItem } from "@/components/ui/tree";
```

```tsx
<Tree aria-label="Files" defaultExpandedKeys={["src"]}>
  <TreeItem id="src" title="src" icon={<FolderIcon />}>
    <TreeItem id="index" title="index.ts" icon={<FileIcon />} />
  </TreeItem>
  <TreeItem id="readme" title="README.md" icon={<FileIcon />} />
</Tree>
```

Nest `TreeItem`s inside a `TreeItem` to give it children; the expand chevron appears automatically. Give every item a unique `id`.

### When to use

* Tree — data with real nesting that users open and close: folders, org charts, category trees, nested settings or permissions.
* [Disclosure](/docs/components/disclosure) — a few collapsible sections of content, not a navigable list of items.
* [Sidebar](/docs/components/sidebar) — app navigation with one or two levels. Use a tree inside it when the hierarchy is deep or user-defined (projects and folders).
* [Grid List](/docs/components/grid-list) or [List Box](/docs/components/list-box) — a flat list.

## Anatomy

```tsx
<Tree>                          {/* role="treegrid" */}
  <TreeItem>                    {/* role="row" aria-level aria-expanded */}
    {/* checkbox (toggle selection) · indent · chevron · icon · title · suffix */}
    <TreeItem />                {/* nested items */}
  </TreeItem>
</Tree>
```

| Part               | Renders                                 | Notes                                                                                             |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `Tree`             | `<div role="treegrid">`                 | React Aria `Tree`. Owns expansion and selection state. `variant="bordered"` frames it as a card.  |
| `TreeItem`         | `<div role="row">`                      | One node. Sets `aria-level`, `aria-expanded` and `aria-selected`.                                 |
| Selection checkbox | [`Checkbox`](/docs/components/checkbox) | Shown with `selectionMode` and the default `selectionBehavior="toggle"`.                          |
| Indent             | `<span>`                                | Width follows React Aria's `--tree-item-level` variable (16px per level).                         |
| Chevron            | `<button slot="chevron">`               | Only on items with children. Rotates when expanded. Not a tab stop; the row handles the keyboard. |
| Icon               | `<span>`                                | `icon`: a node, or a function of the item state (for open/closed folders).                        |
| Suffix             | `<span>`                                | `suffix`: counts, sizes, badges or a status dot, pushed to the end.                               |

## Examples

### Dynamic items

Pass data to `items` and a render function as children. For nested data, render a `Collection` of the node's children inside each `TreeItem`, calling the same function recursively. React Aria only renders expanded branches.

Example `tree/dynamic`: source in https://desyne.dev/docs/components/tree.md

```tsx
<Tree aria-label="Files" items={files}>
  {function renderNode(node) {
    return (
      <TreeItem id={node.id} title={node.name}>
        {node.children && <Collection items={node.children}>{renderNode}</Collection>}
      </TreeItem>
    );
  }}
</Tree>
```

### Multiple selection

`selectionMode="multiple"` adds a checkbox to each row. Selecting a parent doesn't select its children; React Aria treats each row on its own, so select descendants yourself in `onSelectionChange` if your data needs it. `isDisabled` items can't be selected or expanded.

Example `tree/selection`: source in https://desyne.dev/docs/components/tree.md

### Navigation

For a docs or project navigator, use `selectionMode="single"` with `selectionBehavior="replace"`: clicking a row selects it with no checkbox, and the selected row shows the current page. `disallowEmptySelection` keeps one page selected. For links, give items an `href` instead and React Aria navigates on press (use your router's `RouterProvider` for client-side navigation).

Example `tree/navigation`: source in https://desyne.dev/docs/components/tree.md

### Controlled expansion

`expandedKeys` and `onExpandedChange` control which items are open, for "Expand all" and "Collapse all" buttons or to remember the open folders. `suffix` holds an unread count here.

Example `tree/controlled`: source in https://desyne.dev/docs/components/tree.md

## Accessibility

* The tree is a `treegrid`: one tab stop, with arrow keys inside. Give it an `aria-label` or `aria-labelledby`.
* Each row announces its level, position ("3 of 5"), expanded state and selection.
* `title` is the row's accessible name when it's a string. If `title` is JSX, pass `textValue` so type-ahead and screen readers get plain text.
* The chevron and the selection checkbox are inside the row and aren't separate tab stops.
* Icons are decorative; put the meaning in the title (or `textValue`), not only in a folder or lock icon.
* Drag and drop isn't wired up in this component. React Aria's `useDragAndDrop` works with `Tree`; add a `slot="drag"` button to the item content if you need it.

### Keyboard

| Key                              | Action                                                                |
| -------------------------------- | --------------------------------------------------------------------- |
| <kbd>↓</kbd> / <kbd>↑</kbd>      | Next / previous visible row                                           |
| <kbd>→</kbd>                     | Expands a collapsed row; on an expanded row, moves to its first child |
| <kbd>←</kbd>                     | Collapses an expanded row; on a child, moves to its parent            |
| <kbd>Home</kbd> / <kbd>End</kbd> | First / last visible row                                              |
| <kbd>Enter</kbd>                 | Expands or collapses, or runs `onAction` / follows `href`             |
| <kbd>Space</kbd>                 | Toggles selection                                                     |
| Letters                          | Type-ahead to a row by its text                                       |

## Styling

### Data attributes

On each `TreeItem`:

| Attribute                             | Present when                       |
| ------------------------------------- | ---------------------------------- |
| `data-expanded`                       | The item is expanded               |
| `data-has-child-items`                | The item has children              |
| `data-level`                          | Always: the 1-based depth          |
| `data-selected`                       | The item is selected               |
| `data-focused` / `data-focus-visible` | The row has focus / keyboard focus |
| `data-hovered` / `data-pressed`       | Hovered / being pressed            |
| `data-disabled`                       | `isDisabled` is set                |

Items set `--tree-item-level`, which the indent uses. Change the step by editing the indent span's width in the source.

### Data slots

| Slot                            | Element                    |
| ------------------------------- | -------------------------- |
| `data-slot="tree"`              | Root (with `data-variant`) |
| `data-slot="tree-item"`         | A row                      |
| `data-slot="tree-item-content"` | The row's content          |
| `data-slot="tree-item-icon"`    | The icon                   |
| `data-slot="tree-item-title"`   | The title                  |
| `data-slot="tree-item-suffix"`  | The suffix                 |

## API Reference

### Tree

<TypeTable
  type="{
  variant: { type: '&#x22;plain&#x22; | &#x22;bordered&#x22;', default: '&#x22;plain&#x22;', description: &#x22;No frame, or a card with a border and padding.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Data for dynamic trees. Children is then a render function.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;none&#x22;', description: &#x22;Whether rows can be selected.&#x22; },
  selectionBehavior: { type: '&#x22;toggle&#x22; | &#x22;replace&#x22;', default: '&#x22;toggle&#x22;', description: &#x22;toggle shows checkboxes; replace selects on click like a file browser.&#x22; },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, description: &#x22;Prevents deselecting the last selected row.&#x22; },
  expandedKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Controlled expanded rows.&#x22; },
  defaultExpandedKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Initially expanded rows.&#x22; },
  onExpandedChange: { type: &#x22;(keys: Set<Key>) => void&#x22;, description: &#x22;Called when a row expands or collapses.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when a row is activated (Enter, or click with replace / no selection).&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Rows that can't be selected or expanded.&#x22; },
  renderEmptyState: { type: &#x22;(props) => ReactNode&#x22;, description: &#x22;Content when there are no items.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required unless aria-labelledby is set.&#x22; },
  className: { type: &#x22;string | ((state: TreeRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Tree`](https://react-aria.adobe.com/Tree#api).

### TreeItem

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique id, used by selectedKeys and expandedKeys.&#x22; },
  title: { type: &#x22;ReactNode&#x22;, description: &#x22;The row's label.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Plain text for type-ahead and the accessible name. Defaults to title when it's a string.&#x22; },
  icon: { type: &#x22;ReactNode | ((state: TreeItemContentRenderProps) => ReactNode)&#x22;, description: &#x22;Leading icon, or a function of { isExpanded, isSelected, level, … }.&#x22; },
  suffix: { type: &#x22;ReactNode&#x22;, description: &#x22;Trailing content: counts, badges, sizes.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Nested TreeItems (or a Collection).&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables the row.&#x22; },
  hasChildItems: { type: &#x22;boolean&#x22;, description: &#x22;Shows the chevron before children are loaded (for lazy loading).&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Turns the row into a link.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when this row is activated.&#x22; },
  className: { type: &#x22;string | ((state: TreeItemRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`TreeItem`](https://react-aria.adobe.com/Tree#treeitem).

## Related

* [Grid List](/docs/components/grid-list) — a flat interactive list with the same row styles.
* [Sidebar](/docs/components/sidebar) — app navigation that can host a tree.
* [Disclosure](/docs/components/disclosure) — collapsible content sections.

---

# Tag Group

Source: https://desyne.dev/docs/components/tag-group

> A focusable group of compact labels, keywords or filters. Tags can be colored, selected (single or multiple), removed with the keyboard or a button, act as links or actions, and come in soft and outline variants at two sizes.

```tsx title="tag-group/demo.tsx"
"use client";

import { Tag, TagGroup } from "@/components/ui/tag-group";

export default function TagGroupDemo() {
  return (
    <TagGroup
      label="Interests"
      selectionMode="multiple"
      defaultSelectedKeys={["design", "security"]}
    >
      <Tag id="design">Design</Tag>
      <Tag id="engineering">Engineering</Tag>
      <Tag id="security">Security</Tag>
      <Tag id="product">Product</Tag>
      <Tag id="data">Data</Tag>
    </TagGroup>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/tag-group
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

```tsx
import { Tag, TagGroup } from "@/components/ui/tag-group";
```

```tsx
<TagGroup label="Labels">
  <Tag color="danger">bug</Tag>
  <Tag color="info">docs</Tag>
</TagGroup>
```

### When to use

* Tag Group — a set of short labels users scan, filter by or remove: labels on an issue, active filters, selected skills.
* [Badge](/docs/components/badge) — a single, non-interactive status or count.
* [Toggle Button Group](/docs/components/toggle-button-group) — a few mutually exclusive options that behave like buttons in a toolbar.
* [Checkbox Group](/docs/components/checkbox) — many options in a form with their own labels and descriptions.
* [Combo Box](/docs/components/combobox) with a Tag Group — picking from a long list and showing the picks as tags.

## Anatomy

```tsx
<TagGroup>          {/* label, list, description, error */}
  <Tag>             {/* role="row" */}
    <Icon />
    Label
    {/* remove button, when onRemove is set */}
  </Tag>
</TagGroup>
```

| Part                | Renders                  | Notes                                                                         |
| ------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `TagGroup`          | `<div>`                  | Root with `label`, `description` and `errorMessage`. `data-slot="tag-group"`. |
| Tag list            | `<div role="grid">`      | Wrapping flex row of tags. Shows `renderEmptyState` when empty.               |
| `Tag`               | `<div role="row">`       | A tag. Plain-string children become its `textValue`. `data-slot="tag"`.       |
| Remove button       | `<button slot="remove">` | A small ✕, rendered automatically when the group has `onRemove`.              |
| Label               | `<span>`                 | From `label`.                                                                 |
| Description / error | `<span slot="…">`        | From `description` and `errorMessage`.                                        |

## Examples

### Colors

A `color` gives a tag the tinted `soft` look. Without a color, tags use the neutral `outline` style.

Example `tag-group/colors`: source in https://desyne.dev/docs/components/tag-group.md

### Variants

Set `variant` on the group to style every tag: `outline` (default without a color) or `soft`. A `variant` on an individual `Tag` overrides it.

Example `tag-group/variants`: source in https://desyne.dev/docs/components/tag-group.md

### Sizes

`sm` (20px) for dense tables and cards, `md` (24px) by default. Set it on the group or per tag.

Example `tag-group/sizes`: source in https://desyne.dev/docs/components/tag-group.md

### With icons

Icons are sized to 12px automatically. Pass `textValue` when children aren't a plain string.

Example `tag-group/icons`: source in https://desyne.dev/docs/components/tag-group.md

### Single selection

`selectionMode="single"` turns tags into choice chips. Add `disallowEmptySelection` so one is always selected. Selected tags always use the solid primary style.

Example `tag-group/single-selection`: source in https://desyne.dev/docs/components/tag-group.md

### Controlled selection

`selectedKeys` and `onSelectionChange` own the selection in `multiple` mode. Handle both a `Set` of keys and `"all"`.

Example `tag-group/controlled`: source in https://desyne.dev/docs/components/tag-group.md

### Removable tags

`onRemove` adds a remove button to every tag and enables <kbd>Backspace</kbd> / <kbd>Delete</kbd>. It receives the keys to remove; `useListData` makes updating the list a one-liner. `renderEmptyState` shows when the last tag is gone.

Example `tag-group/removable`: source in https://desyne.dev/docs/components/tag-group.md

### Disabled tags

`disabledKeys` keeps tags visible but not focusable, selectable or removable.

Example `tag-group/disabled`: source in https://desyne.dev/docs/components/tag-group.md

### Actions

`onAction` makes tags actionable without selecting them, for suggestions and quick filters.

Example `tag-group/actions`: source in https://desyne.dev/docs/components/tag-group.md

### Links

Give tags an `href` to render them as links. They work with client-side routers through React Aria's `RouterProvider`.

Example `tag-group/links`: source in https://desyne.dev/docs/components/tag-group.md

### Description and error

`description` explains the group; `errorMessage` replaces it with red text. Both are linked to the tag list for screen readers. Tag groups have no built-in validation, so decide when to show the error yourself.

Example `tag-group/validation`: source in https://desyne.dev/docs/components/tag-group.md

## Recipes

### Tag input

A [`TextField`](/docs/components/text-field) adds a tag on <kbd>Enter</kbd>, with duplicate detection and a maximum count. The tags below are removable.

Example `tag-group/recipe-tag-input`: source in https://desyne.dev/docs/components/tag-group.md

### Filter chips

Pill-shaped, single-select chips that filter a list. `disallowEmptySelection` guarantees an active filter.

Example `tag-group/recipe-filter-chips`: source in https://desyne.dev/docs/components/tag-group.md

### Active filters bar

Removable `soft` tags that summarize applied filters, with a "Clear all" action. Each tag's `textValue` reads the field and value together.

Example `tag-group/recipe-active-filters`: source in https://desyne.dev/docs/components/tag-group.md

## Accessibility

* The tag list is a `role="grid"` and each tag a `role="row"`, so screen readers announce position and selected state. The group is labelled by `label` (or `aria-label`).
* The whole group is one tab stop; arrow keys move between tags. If the last tag is removed while focused, focus moves to the list itself so it isn't lost.
* Remove buttons are labelled "Remove" together with the tag text. Keyboard users can also press <kbd>Backspace</kbd> / <kbd>Delete</kbd> on the focused tag.
* `description` and `errorMessage` are linked with `aria-describedby`.
* Colors are decoration only. Put the meaning in the text ("bug", "blocked"), not just the color.

### Keyboard

| Key                                      | Action                                                 |
| ---------------------------------------- | ------------------------------------------------------ |
| <kbd>Tab</kbd>                           | Moves focus into and out of the group                  |
| <kbd>←</kbd> / <kbd>→</kbd>              | Moves between tags (reversed in RTL)                   |
| <kbd>Home</kbd> / <kbd>End</kbd>         | Moves to the first / last tag                          |
| <kbd>Space</kbd> / <kbd>Enter</kbd>      | Selects the tag, triggers `onAction` or follows a link |
| <kbd>Backspace</kbd> / <kbd>Delete</kbd> | Removes the focused tag (with `onRemove`)              |
| <kbd>Esc</kbd>                           | Clears the selection                                   |

## Styling

### Data attributes

On each `Tag`:

| Attribute                             | Present when                              |
| ------------------------------------- | ----------------------------------------- |
| `data-selected`                       | The tag is selected (solid primary style) |
| `data-focused` / `data-focus-visible` | The tag has focus / keyboard focus        |
| `data-hovered` / `data-pressed`       | Hovered with a mouse / being pressed      |
| `data-disabled`                       | The tag is disabled                       |
| `data-allows-removing`                | The group has `onRemove`                  |
| `data-selection-mode`                 | `single` or `multiple`                    |

On the tag list (the element with `role="grid"`): `data-empty`, `data-focused`, `data-focus-visible`. The root `TagGroup` is a Tailwind group (`group/field`).

### Slots

| `data-slot`            | Element    |
| ---------------------- | ---------- |
| `tag-group`            | Root       |
| `tag`                  | Each tag   |
| `label`, `description` | Field text |

### Tone variables

Like [Button](/docs/components/button#tone-variables), tag colors come from the `--tone` variable, so a one-off color is just a class:

```tsx
<Tag color="primary" className="[--tone:var(--color-pink-600)]">design</Tag>
```

* `className` on `TagGroup` styles the root (a string). `className` on `Tag` accepts a function of the render props.
* Add `rounded-full px-3` to a `Tag` for pill-shaped chips.

## API Reference

### TagGroup

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label. Required unless you pass aria-label or aria-labelledby.&#x22; },
  description: { type: &#x22;ReactNode&#x22;, description: &#x22;Helper text under the tags.&#x22; },
  errorMessage: { type: &#x22;string&#x22;, description: &#x22;Error text shown under the tags when set.&#x22; },
  variant: { type: '&#x22;soft&#x22; | &#x22;outline&#x22;', description: &#x22;Style for every tag. Defaults per tag: soft with a color, outline without.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Size for every tag.&#x22; },
  items: { type: &#x22;Iterable<T>&#x22;, description: &#x22;Items for dynamic rendering with a children function.&#x22; },
  children: { type: &#x22;ReactNode | ((item: T) => ReactNode)&#x22;, description: &#x22;Static Tags, or a render function.&#x22; },
  renderEmptyState: { type: &#x22;(props: TagListRenderProps) => ReactNode&#x22;, description: &#x22;Content shown when there are no tags.&#x22; },
  selectionMode: { type: '&#x22;none&#x22; | &#x22;single&#x22; | &#x22;multiple&#x22;', default: '&#x22;none&#x22;' },
  selectionBehavior: { type: '&#x22;toggle&#x22; | &#x22;replace&#x22;', default: '&#x22;toggle&#x22;' },
  selectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Controlled selection.&#x22; },
  defaultSelectedKeys: { type: '&#x22;all&#x22; | Iterable<Key>', description: &#x22;Uncontrolled initial selection.&#x22; },
  onSelectionChange: { type: &#x22;(keys: Selection) => void&#x22;, description: &#x22;Called when the selection changes.&#x22; },
  disallowEmptySelection: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Prevents deselecting the last tag.&#x22; },
  disabledKeys: { type: &#x22;Iterable<Key>&#x22;, description: &#x22;Tags that are disabled.&#x22; },
  onRemove: { type: &#x22;(keys: Set<Key>) => void&#x22;, description: &#x22;Enables removal and adds remove buttons.&#x22; },
  onAction: { type: &#x22;(key: Key) => void&#x22;, description: &#x22;Called when a tag is actioned.&#x22; },
  escapeKeyBehavior: { type: '&#x22;clearSelection&#x22; | &#x22;none&#x22;', default: '&#x22;clearSelection&#x22;' },
  shouldSelectOnPressUp: { type: &#x22;boolean&#x22;, description: &#x22;Selects on pointer up instead of down.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the root.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`TagGroup`](https://react-aria.adobe.com/TagGroup#api).

### Tag

<TypeTable
  type="{
  id: { type: &#x22;Key&#x22;, description: &#x22;Unique key. Set automatically from item.id with dynamic items.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', description: &#x22;Tone. Implies the soft variant unless the group or tag sets one.&#x22; },
  variant: { type: '&#x22;soft&#x22; | &#x22;outline&#x22;', description: &#x22;Overrides the group's variant.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', description: &#x22;Overrides the group's size.&#x22; },
  textValue: { type: &#x22;string&#x22;, description: &#x22;Accessible text. Required when children aren't a plain string.&#x22; },
  isDisabled: { type: &#x22;boolean&#x22;, description: &#x22;Disables this tag.&#x22; },
  href: { type: &#x22;string&#x22;, description: &#x22;Renders the tag as a link.&#x22; },
  onAction: { type: &#x22;() => void&#x22;, description: &#x22;Called when this tag is actioned.&#x22; },
  className: { type: &#x22;string | ((state: TagRenderProps) => string)&#x22; },
  children: { type: &#x22;ReactNode | ((state: TagRenderProps) => ReactNode)&#x22; },
}"
/>

## Related

* [Badge](/docs/components/badge) — static status labels with the same colors.
* [Combo Box](/docs/components/combobox) — pick from a long list, then show picks as tags.
* [Toggle Button Group](/docs/components/toggle-button-group) — segmented choices.
* [List Box](/docs/components/list-box) — a vertical list of selectable options.

---

# Card

Source: https://desyne.dev/docs/components/card

> A surface that groups related content and actions. Four surface styles, three padding sizes, a header with an action slot and optional hairline, an inset surface for previews, and a footer for actions. Server-component safe.

```tsx title="card/demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { TextField } from "@/components/ui/text-field";

export default function CardDemo() {
  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Sign in</CardTitle>
        <CardDescription>Welcome back. Enter your details.</CardDescription>
        <CardAction>
          <Button variant="link" size="sm">
            Sign up
          </Button>
        </CardAction>
      </CardHeader>
      <CardContent className="grid gap-4">
        <TextField label="Email" type="email" placeholder="you@company.com" />
        <TextField label="Password" type="password" />
      </CardContent>
      <CardFooter className="flex-col">
        <Button className="w-full">Sign in</Button>
        <Button variant="outline" className="w-full">
          Continue with Google
        </Button>
      </CardFooter>
    </Card>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/card
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

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

```tsx
<Card>
  <CardHeader>
    <CardTitle>Usage this month</CardTitle>
    <CardDescription>Resets on the 1st.</CardDescription>
  </CardHeader>
  <CardContent>…</CardContent>
  <CardFooter>…</CardFooter>
</Card>
```

<Callout title="Plain elements, no client JavaScript">
  Every card part is a styled `<div>` with no React Aria behavior and no
  `"use client"` directive, so cards render in server components. Put
  interactive children (buttons, fields, links) inside and they bring their own
  behavior.
</Callout>

### When to use

* Card: a self-contained group of content with its own heading, such as a stat, a settings section, a pricing tier or a preview.
* [Item](/docs/components/item): a single row inside a list (media, a title, a quiet second line and actions). Stack items inside a card rather than stacking cards.
* [Alert](/docs/components/alert): a message that needs attention, not a container.
* [Dialog](/docs/components/dialog) or [Sheet](/docs/components/sheet): content that should interrupt or overlay the page.
* Avoid wrapping a whole page in one card, and avoid nesting outline cards; use `filled` or `CardInset` for an inner surface.

## Anatomy

```tsx
<Card>                  {/* surface: variant, size (sets --card-px) */}
  <CardHeader>          {/* grid: title + description, action on the right */}
    <CardTitle />       {/* a leading svg becomes an icon */}
    <CardDescription />
    <CardAction />      {/* top-right slot: button, badge, menu */}
  </CardHeader>
  <CardContent>         {/* horizontally padded body */}
    <CardInset />       {/* optional muted inner surface */}
  </CardContent>
  <CardFooter />        {/* row of actions or meta text */}
</Card>
```

| Part              | Renders | Notes                                                                                                                   |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `Card`            | `<div>` | Root. Flex column with vertical padding and a gap between parts. Sets the `--card-px` variable used by the other parts. |
| `CardHeader`      | `<div>` | Two-row grid. Switches to two columns when it contains a `CardAction`. `separator` draws an inset hairline underneath.  |
| `CardTitle`       | `<div>` | Medium-weight title. Any direct `svg` child is sized to 16px and spaced as a leading icon.                              |
| `CardDescription` | `<div>` | Muted supporting text.                                                                                                  |
| `CardAction`      | `<div>` | Pinned to the top-right of the header, spanning both rows.                                                              |
| `CardContent`     | `<div>` | Adds the card's horizontal padding.                                                                                     |
| `CardInset`       | `<div>` | A rounded, muted surface for previews, code, media or empty states. Add your own padding.                               |
| `CardFooter`      | `<div>` | Horizontal flex row with the card's horizontal padding.                                                                 |

The parts render as `<div>` for layout flexibility. `CardTitle` is not a heading element; if the card title should appear in the document outline, put an `<h2>`/`<h3>` inside it.

## Examples

### Variants

`outline` is the default and suits most dashboard surfaces. `elevated` lifts featured content with a soft shadow, `filled` is a muted panel with no border for secondary or nested content, and `ghost` keeps the spacing and slots with no surface at all.

Example `card/variants`: source in https://desyne.dev/docs/components/card.md

### Sizes

`size` controls the vertical padding, the gap between parts and the `--card-px` horizontal padding every part reads. `sm` (12px) suits dense grids, `md` (16px) is the default and `lg` (24px) suits forms and focused content.

Example `card/sizes`: source in https://desyne.dev/docs/components/card.md

### Header, action and inset

Pass `separator` to `CardHeader` for an inset hairline aligned with the content. An svg inside `CardTitle` becomes a leading icon, `CardAction` holds one quiet action in the top-right corner, and `CardInset` is the muted surface for the headline figure.

Example `card/widget`: source in https://desyne.dev/docs/components/card.md

### Bordered header and footer

Add `border-b` to `CardHeader` or `border-t` to `CardFooter` for full-width dividers; the parts add matching padding on the bordered side automatically. Use this for settings sections where the footer holds the save action.

Example `card/footer`: source in https://desyne.dev/docs/components/card.md

### Media

For an edge-to-edge cover, remove the top padding with `pt-0` and clip the corners with `overflow-hidden`. The cover can be an image, video or illustration.

Example `card/media`: source in https://desyne.dev/docs/components/card.md

### Stat cards

A description, a large tabular value in `CardTitle` and a trend [`Badge`](/docs/components/badge) in `CardAction` make a compact KPI tile. Use `size="sm"` in grids.

Example `card/stats`: source in https://desyne.dev/docs/components/card.md

### Interactive cards

`isInteractive` only adds a pointer cursor and hover feedback; it does not make the card focusable or clickable. Put a real link inside and stretch it over the card with an `after:absolute after:inset-0` overlay, so middle-click, "open in new tab" and keyboard focus keep working. `has-[a:focus-visible]` moves the focus ring to the card.

Example `card/interactive`: source in https://desyne.dev/docs/components/card.md

### Loading

Mirror the final layout with [`Skeleton`](/docs/components/skeleton) blocks so nothing shifts when data arrives. Mark the card `aria-busy` while it loads.

Example `card/loading`: source in https://desyne.dev/docs/components/card.md

### Empty state

Use `CardInset` as a quiet frame for an empty state, with one clear action to fill it.

Example `card/empty`: source in https://desyne.dev/docs/components/card.md

## Recipes

### Pricing tiers

Two tiers side by side. The featured plan uses `elevated` with a ring and a "Popular" badge in `CardAction`; `size="lg"` gives the content room.

Example `card/recipe-pricing`: source in https://desyne.dev/docs/components/card.md

### Settings section

A notification settings panel: a header with an icon and hairline, a list of [`Switch`](/docs/components/switch)es with descriptions, and a bordered footer for the save action.

Example `card/recipe-settings`: source in https://desyne.dev/docs/components/card.md

### Team members

A card that holds a list of [`Item`](/docs/components/item) rows with [`Avatar`](/docs/components/avatar)s, role badges and a per-row menu button. `px-2` on `CardContent` lets row hover backgrounds reach closer to the edge.

Example `card/recipe-team`: source in https://desyne.dev/docs/components/card.md

## Accessibility

* Cards have no role. They're visual grouping only; screen readers read the content in order.
* `CardTitle` renders a `<div>`. When the card's title is a real section heading, render a heading element inside it (for example `<CardTitle><h3>…</h3></CardTitle>`) so it shows up in the heading outline.
* For a card that navigates, use a real link (see [Interactive cards](#interactive-cards)); don't put `onClick` on the card `<div>`. Keep other interactive elements outside the stretched link's overlay, or raise them with `relative z-10`.
* `isInteractive` is purely visual. It doesn't add focus, a role or keyboard handling.
* If a card is a meaningful landmark (for example a named region of a dashboard), add `role="region"` and `aria-labelledby` pointing at its title.

## Styling

### Data attributes

| Attribute                      | On                | Present when                                                       |
| ------------------------------ | ----------------- | ------------------------------------------------------------------ |
| `data-slot="card"`             | `Card`            | Always                                                             |
| `data-slot="card-header"`      | `CardHeader`      | Always                                                             |
| `data-separator`               | `CardHeader`      | `separator` is true                                                |
| `data-slot="card-title"`       | `CardTitle`       | Always                                                             |
| `data-slot="card-description"` | `CardDescription` | Always                                                             |
| `data-slot="card-action"`      | `CardAction`      | Always. `CardHeader` switches to two columns when it contains one. |
| `data-slot="card-content"`     | `CardContent`     | Always                                                             |
| `data-slot="card-inset"`       | `CardInset`       | Always                                                             |
| `data-slot="card-footer"`      | `CardFooter`      | Always                                                             |

`Card` also sets the `group/card` Tailwind group, so children can react to hover with `group-hover/card:…`.

### Padding variable

Every part reads its horizontal padding from `--card-px`, which `size` sets. Override it to change the padding everywhere at once:

```tsx
<Card className="[--card-px:--spacing(5)]">…</Card>
```

### `cardVariants`

The `tailwind-variants` function behind `Card`. Use it to give another element (a `<section>`, a link, a React Aria `GridListItem`) the card surface.

```tsx
import { cardVariants } from "@/components/ui/card";

<section className={cardVariants({ variant: "elevated", size: "lg" })}>…</section>;
```

## API Reference

### Card

<TypeTable
  type="{
  variant: {
    type: '&#x22;outline&#x22; | &#x22;elevated&#x22; | &#x22;filled&#x22; | &#x22;ghost&#x22;',
    default: '&#x22;outline&#x22;',
    description: &#x22;Surface style: hairline border, soft shadow, muted fill, or none.&#x22;,
  },
  size: {
    type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;',
    default: '&#x22;md&#x22;',
    description: &#x22;Vertical padding, gap between parts, and the --card-px horizontal padding (12, 16 or 24px).&#x22;,
  },
  isInteractive: {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Adds a pointer cursor and hover border and shadow. Visual only.&#x22;,
  },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### CardHeader

<TypeTable
  type="{
  separator: {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Draws an inset hairline under the header, aligned with the card's content.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### CardTitle / CardDescription / CardAction / CardContent / CardInset / CardFooter

No extra props. Each accepts every prop of `<div>`.

### cardVariants

<TypeTable
  type="{
  variant: { type: &#x22;CardProps['variant']&#x22;, default: '&#x22;outline&#x22;' },
  size: { type: &#x22;CardProps['size']&#x22;, default: '&#x22;md&#x22;' },
  isInteractive: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Item](/docs/components/item): list rows to place inside a card.
* [Badge](/docs/components/badge): status and trend labels for card actions.
* [Skeleton](/docs/components/skeleton): loading placeholders that match a card's layout.
* [Separator](/docs/components/separator): dividers between sections of a card.

---

# Badge

Source: https://desyne.dev/docs/components/badge

> A small, non-interactive label for status, counts, versions and categories. Four styles including a status dot, seven tone colors, two sizes, a pill shape, and a `badgeVariants` helper for links and custom elements.

```tsx title="badge/demo.tsx"
"use client";

import { Badge } from "@/components/ui/badge";

export default function BadgeDemo() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Badge>Draft</Badge>
      <Badge color="success">Active</Badge>
      <Badge color="warning">Pending review</Badge>
      <Badge color="danger">Failed</Badge>
      <Badge variant="solid" color="primary">
        New
      </Badge>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/badge
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

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

```tsx
<Badge color="success">Active</Badge>
```

A badge with no props is a neutral `soft` label. It renders a plain `<span>` with no client JavaScript, so it works in server components.

### When to use

* Badge: a short, read-only label that describes something next to it, such as a status, a count, a version or a category.
* [Tag Group](/docs/components/tag-group): labels the user can select, remove or navigate with the keyboard.
* [Button](/docs/components/button): anything that performs an action. If a badge needs to be clickable, render a link or button with [`badgeVariants`](#as-a-link) instead.
* [Alert](/docs/components/alert): a message that needs a sentence of explanation.
* Keep badge text to one or two words. Rely on the text, not the color alone, to carry the meaning.

## Anatomy

```tsx
<Badge>
  <Icon />   {/* optional, auto-sized to 12px */}
  Label
</Badge>
```

| Part    | Renders    | Notes                                                                                   |
| ------- | ---------- | --------------------------------------------------------------------------------------- |
| `Badge` | `<span>`   | Root. Inline flex, no wrapping, `tabular-nums` for counts. Carries `data-slot="badge"`. |
| Icon    | `<svg>`    | Any direct svg child is sized to 12px and ignores pointer events.                       |
| Dot     | `::before` | Drawn by the `dot` variant in the tone color. Not a separate element.                   |

## Examples

### Variants and colors

`soft` (the default) suits most labels, `solid` draws the eye for "New" or unread counts, `outline` is the quietest, and `dot` pairs a colored dot with neutral text. Every variant works with every color; `neutral` is the default color.

Example `badge/variants`: source in https://desyne.dev/docs/components/badge.md

### Sizes

`md` (24px) is the default. Use `sm` (20px) inside table cells, list rows, buttons and next to small text.

Example `badge/sizes`: source in https://desyne.dev/docs/components/badge.md

### Shapes

`shape="pill"` fully rounds the badge. For a round count, combine `pill` with `min-w-5 px-1` so single digits stay circular.

Example `badge/shapes`: source in https://desyne.dev/docs/components/badge.md

### With icon

Put a lucide icon before the label. It's sized and spaced automatically, and adds recognition without relying on color.

Example `badge/with-icon`: source in https://desyne.dev/docs/components/badge.md

### Status dot

`variant="dot"` keeps the text neutral and puts the meaning in a small dot. It reads calmly in dense status columns where a column of colored backgrounds would be noisy.

Example `badge/dot`: source in https://desyne.dev/docs/components/badge.md

### Counts

Position a badge over an icon button for unread counts, or place it inline inside a button. When the badge overlays an icon button, include the count in the button's `aria-label` and hide the badge with `aria-hidden` so it isn't announced twice.

Example `badge/count`: source in https://desyne.dev/docs/components/badge.md

### As a link

`Badge` renders a `<span>` and isn't interactive. For clickable labels, apply `badgeVariants` to a React Aria `Link` (or a Next.js `Link`) and add hover and focus styles.

Example `badge/as-link`: source in https://desyne.dev/docs/components/badge.md

### Custom colors

Colors are applied through the `--tone` and `--tone-fg` variables, so any color works as a one-off. Pass a non-neutral `color` (neutral `soft` and `outline` use fixed surface colors) and override `--tone`; for `solid`, also set `--tone-fg` for the text.

Example `badge/custom-color`: source in https://desyne.dev/docs/components/badge.md

## Recipes

### Deployment list

An environment badge and a fixed-width status `dot` badge per row, so the status column lines up.

Example `badge/recipe-deployments`: source in https://desyne.dev/docs/components/badge.md

### Navigation counts

Pill counts at the end of navigation links. Unread counts use `solid` to stand out; totals stay `soft`.

Example `badge/recipe-nav-counts`: source in https://desyne.dev/docs/components/badge.md

### Profile header

A verified badge next to a name, and small `outline` badges for skills with one `solid` role badge.

Example `badge/recipe-profile`: source in https://desyne.dev/docs/components/badge.md

## Accessibility

* A badge is a plain `<span>`; screen readers read its text inline with the surrounding content. It has no role and isn't focusable.
* Don't rely on color alone. The text (or an icon plus text) must carry the meaning; the `dot` variant's dot is decorative.
* For bare numbers, give context: "3" next to a bell icon means nothing when read out. Put the full phrase in the parent control's `aria-label` (for example "Notifications, 3 unread") and mark the badge `aria-hidden`, or add visually hidden text.
* `warning` `soft` and `outline` badges darken the text in light mode so it keeps enough contrast on light backgrounds.
* Clickable badges must be real links or buttons. See [As a link](#as-a-link).

## Styling

### Data attributes

| Attribute           | Present when                                                      |
| ------------------- | ----------------------------------------------------------------- |
| `data-slot="badge"` | Always. Target badges from a parent with `*:data-[slot=badge]:…`. |

### Tone variables

| Variable    | Used for                                                                     |
| ----------- | ---------------------------------------------------------------------------- |
| `--tone`    | Background (`solid`), text, border and tint (`soft`, `outline`), dot (`dot`) |
| `--tone-fg` | Text on `solid` badges                                                       |

```tsx
<Badge color="primary" className="[--tone:var(--color-violet-600)]">
  Design
</Badge>
```

The shared `tones` map in `@/lib/primitive` holds the classes for each named color if you want to reuse them on your own elements.

### `badgeVariants`

The `tailwind-variants` function behind the component. Use it to style links, buttons or table cells as badges.

```tsx
import { badgeVariants } from "@/components/ui/badge";

badgeVariants({ variant: "outline", color: "info", size: "sm", shape: "pill" });
```

## API Reference

### Badge

<TypeTable
  type="{
  variant: {
    type: '&#x22;solid&#x22; | &#x22;soft&#x22; | &#x22;outline&#x22; | &#x22;dot&#x22;',
    default: '&#x22;soft&#x22;',
    description: 'Visual style. The shadcn names &#x22;default&#x22; (solid primary), &#x22;secondary&#x22; (soft neutral) and &#x22;destructive&#x22; (solid danger) are accepted as aliases.',
  },
  color: {
    type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;',
    default: '&#x22;neutral&#x22;',
    description: &#x22;Tone color. When a shadcn alias is used as variant, its color applies unless you pass one.&#x22;,
  },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Height 20px or 24px.&#x22; },
  shape: { type: '&#x22;default&#x22; | &#x22;pill&#x22;', default: '&#x22;default&#x22;', description: &#x22;pill makes the badge fully rounded.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Label text and an optional leading icon.&#x22; },
}"
/>

Also accepts every prop of `<span>` except `color`.

### badgeVariants

<TypeTable
  type="{
  variant: { type: '&#x22;solid&#x22; | &#x22;soft&#x22; | &#x22;outline&#x22; | &#x22;dot&#x22;', default: '&#x22;soft&#x22;', description: &#x22;Aliases are not mapped here; use the four real variants.&#x22; },
  color: { type: &#x22;Tone&#x22;, default: '&#x22;neutral&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;' },
  shape: { type: '&#x22;default&#x22; | &#x22;pill&#x22;', default: '&#x22;default&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Tag Group](/docs/components/tag-group): interactive, removable labels.
* [Avatar](/docs/components/avatar): user images with a presence dot.
* [Table](/docs/components/table): status columns are a common home for `dot` badges.
* [Button](/docs/components/button): for anything clickable.

---

# Avatar

Source: https://desyne.dev/docs/components/avatar

> A user or workspace image with an automatic fallback to initials or an icon while it loads or when it fails. Five sizes, circle and square shapes, deterministic fallback colors, a presence dot, and stacked groups with a "+N" overflow.

```tsx title="avatar/demo.tsx"
"use client";

import { Avatar } from "@/components/ui/avatar";

export default function AvatarDemo() {
  return (
    <div className="flex items-center gap-4">
      <Avatar
        size="lg"
        src="https://github.com/shadcn.png"
        alt="shadcn"
        fallback="CN"
        status="online"
      />
      <Avatar
        size="lg"
        colorful
        alt="Nischal Timalsina"
        fallback="NT"
        status="busy"
      />
      <Avatar
        size="lg"
        colorful
        alt="Olivia Martin"
        fallback="OM"
        status="away"
      />
      <Avatar size="lg" fallback="?" status="offline" />
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/avatar
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

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

```tsx
<Avatar src={user.image} alt={user.name} fallback="OM" />
```

<Callout title="One component, no sub-parts">
  Unlike shadcn's `Avatar` / `AvatarImage` / `AvatarFallback` trio, this avatar
  takes `src`, `alt` and `fallback` as props. It tracks the image's loading
  state itself and shows the fallback until the image has loaded, or for good
  if it fails.
</Callout>

### When to use

* Avatar: to identify a person, team or workspace next to their name or content.
* [Badge](/docs/components/badge): for a status label; use the avatar's `status` prop for presence.
* [Item](/docs/components/item): a list row with an avatar as its media, a name and a secondary line.
* Use `shape="square"` for organizations, workspaces and apps, and circles for people, so the two are easy to tell apart.

## Anatomy

```tsx
<AvatarGroup max={4}>        {/* optional stack with a "+N" overflow */}
  <Avatar                    {/* root span: size, shape */}
    src="…"                  {/* <img>, shown once loaded */}
    fallback="OM"            {/* initials or icon while loading / on error */}
    status="online"          {/* presence dot in the corner */}
  />
</AvatarGroup>
```

| Part          | Renders             | Notes                                                                                                      |
| ------------- | ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Avatar`      | `<span>`            | Root. Sized by `size`, carries `data-slot="avatar"`.                                                       |
| Image         | `<img>`             | Rendered when `src` is set. Hidden (but still loading) until it fires `load`; removed if it fires `error`. |
| Fallback      | `<span>`            | The `fallback` content, shown while the image loads or after it fails. Tinted when `colorful` is set.      |
| Status        | `<span role="img">` | A dot sized to 28% of the avatar, labelled with the status name.                                           |
| `AvatarGroup` | `<div>`             | Overlaps its children and adds a ring around each. With `max`, renders a "+N" avatar for the rest.         |

## Examples

### Sizes

`md` (32px) is the default. `xs` and `sm` fit inline text, table rows and dense lists; `lg` and `xl` suit headers and profile cards. Fallback text scales with the size.

Example `avatar/sizes`: source in https://desyne.dev/docs/components/avatar.md

### Shapes

`circle` (default) for people, `square` for organizations, workspaces and apps.

Example `avatar/shapes`: source in https://desyne.dev/docs/components/avatar.md

### Fallbacks

The fallback shows while the image loads, and stays if it fails to load or there's no `src`. Pass initials, or any node such as an icon for guests. Always pass `alt` with the person's name: it becomes the image's alt text, and the fallback's accessible name when no image is shown.

Example `avatar/fallback`: source in https://desyne.dev/docs/components/avatar.md

### Colorful fallbacks

`colorful` tints the fallback with one of six soft palettes, picked from a hash of `alt` (or the fallback text when `alt` is empty). The same name always gets the same color, so people are recognizable across the app, in light and dark mode.

Example `avatar/colorful`: source in https://desyne.dev/docs/components/avatar.md

### Status

`status` adds a presence dot in the bottom-right corner: `online` (success), `busy` (danger), `away` (warning) or `offline` (muted). The dot has a background-colored ring so it stays visible on any surface.

Example `avatar/status`: source in https://desyne.dev/docs/components/avatar.md

### With name

Next to a visible name, pass `alt=""` so the name isn't read twice; the image (or fallback) is then treated as decorative.

Example `avatar/with-text`: source in https://desyne.dev/docs/components/avatar.md

### Group

`AvatarGroup` overlaps avatars and rings each one with the background color. `max` shows that many avatars and collapses the rest into a "+N" avatar. Its `size` prop sizes the "+N" avatar and every child that doesn't set its own `size`, so you set it once on the group. A child with an explicit `size` keeps it. Tighten the overlap with a `-space-x-*` class.

Example `avatar/group`: source in https://desyne.dev/docs/components/avatar.md

## Recipes

### Account menu

An avatar as the trigger of a [`Menu`](/docs/components/menu). Wrap it in a React Aria `Button` with an `aria-label`, since the avatar alone isn't focusable.

Example `avatar/recipe-account-menu`: source in https://desyne.dev/docs/components/avatar.md

### Comment thread

A list of comments with avatars aligned to the first line of each message.

Example `avatar/recipe-comments`: source in https://desyne.dev/docs/components/avatar.md

### Project card

A square workspace avatar in a [`Card`](/docs/components/card) header and a small `AvatarGroup` of the team in the footer.

Example `avatar/recipe-project-card`: source in https://desyne.dev/docs/components/avatar.md

## Accessibility

* With an image, `alt` is the image's alt text. When no image is shown and `alt` is set, the fallback gets `role="img"` and `aria-label={alt}`.
* While an image is still loading, the fallback is `aria-hidden` and the (invisible) `<img>` carries the name.
* With `alt=""` (the default), the avatar is decorative: the image has empty alt text and the fallback is `aria-hidden`. Use this when the name is already visible next to the avatar.
* The status dot is `role="img"` with `aria-label` set to the status name ("online", "busy", "away", "offline"), so it's announced as a separate image. If presence is shown elsewhere in text, you can omit `status`.
* The "+N" avatar in a group has `aria-label="N more"`. Give the group itself `role="group"` and an `aria-label` such as "6 collaborators" for context.
* Avatars aren't interactive. To make one clickable, wrap it in a button or link with an accessible name, as in the [account menu](#account-menu) recipe.

## Styling

### Data attributes

| Attribute                  | On            | Present when |
| -------------------------- | ------------- | ------------ |
| `data-slot="avatar"`       | `Avatar` root | Always       |
| `data-slot="avatar-group"` | `AvatarGroup` | Always       |

`AvatarGroup` styles its children through `*:data-[slot=avatar]:…` (ring and full rounding), so anything you render inside with `data-slot="avatar"` joins the stack.

### Customizing

* `className` on `Avatar` goes to the root span; use it for custom sizes (`size-12 text-base`) or rings.
* The ring color in groups is `ring-background`. Override it on a colored surface with `*:data-[slot=avatar]:ring-card` on the group.
* `colorful` palettes are defined in the component source as OKLCH values with dark-mode pairs. Edit that array to match your brand.

## API Reference

### Avatar

<TypeTable
  type="{
  src: { type: &#x22;string&#x22;, description: &#x22;Image URL. The fallback shows until it loads, and replaces it if it fails.&#x22; },
  alt: {
    type: &#x22;string&#x22;,
    default: '&#x22;&#x22;',
    description: &#x22;Name of the person or entity. Used as alt text, as the fallback's accessible name, and as the colorful seed. Empty means decorative.&#x22;,
  },
  fallback: { type: &#x22;ReactNode&#x22;, description: &#x22;Shown while the image loads or when it fails. Usually initials or an icon.&#x22; },
  size: { type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;', default: '&#x22;md&#x22;', description: &#x22;20, 24, 32, 40 or 56px.&#x22; },
  shape: { type: '&#x22;circle&#x22; | &#x22;square&#x22;', default: '&#x22;circle&#x22;' },
  colorful: {
    type: &#x22;boolean&#x22;,
    default: &#x22;false&#x22;,
    description: &#x22;Tints the fallback with a palette derived from alt (or the fallback text).&#x22;,
  },
  status: { type: '&#x22;online&#x22; | &#x22;busy&#x22; | &#x22;away&#x22; | &#x22;offline&#x22;', description: &#x22;Presence dot in the bottom-right corner.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the root span.&#x22; },
}"
/>

Also accepts every prop of `<span>`.

### AvatarGroup

<TypeTable
  type="{
  max: { type: &#x22;number&#x22;, description: &#x22;Show at most this many children, then a \&#x22;+N\&#x22; avatar for the rest.&#x22; },
  size: {
    type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;',
    default: '&#x22;md&#x22;',
    description: &#x22;Size of the \&#x22;+N\&#x22; avatar and of children that don't set their own size. An explicit size on a child wins.&#x22;,
  },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Avatar elements.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the wrapper, e.g. -space-x-1 to change the overlap.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

## Related

* [Item](/docs/components/item): list rows with an avatar as media.
* [Badge](/docs/components/badge): labels next to a name, like roles or "Verified".
* [Menu](/docs/components/menu): account menus triggered by an avatar.
* [Card](/docs/components/card): profile and project cards.

---

# Separator

Source: https://desyne.dev/docs/components/separator

> A thin horizontal or vertical rule that separates content, with an optional inline label ("or", a date) placed at the start, center or end, and a dashed style. Built on React Aria's Separator, so it's announced correctly.

```tsx title="separator/demo.tsx"
"use client";

import { Separator } from "@/components/ui/separator";

export default function SeparatorDemo() {
  return (
    <div className="w-full max-w-sm">
      <div className="flex flex-col gap-1">
        <h4 className="font-medium text-sm">Desyne</h4>
        <p className="text-muted-foreground text-sm">
          Accessible React components with shadcn tokens.
        </p>
      </div>
      <Separator className="my-4" />
      <div className="flex h-5 items-center gap-4 text-sm">
        <span>Docs</span>
        <Separator orientation="vertical" />
        <span>Components</span>
        <Separator orientation="vertical" />
        <span>Templates</span>
      </div>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/separator
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { Separator } from "@/components/ui/separator";
```

```tsx
<Separator />
<Separator orientation="vertical" />
<Separator label="or" />
```

### When to use

* Separator: to divide groups of content that belong to the same surface, such as sections of a form, groups in a toolbar or items in a breadcrumb-like row.
* Spacing alone is often enough. Reach for a separator when whitespace doesn't make the grouping clear.
* [Card](/docs/components/card): when the groups need their own surface. `CardHeader` has its own `separator` prop.
* Inside menus, use [`MenuSeparator`](/docs/components/menu); between list rows, use [`ItemSeparator`](/docs/components/item).

## Anatomy

A separator is a single element. The labelled version draws the two lines with `::before` and `::after`.

```tsx
<Separator />                 {/* <hr> */}
<Separator orientation="vertical" />   {/* <div role="separator"> */}
<Separator label="or" />      {/* line · label · line */}
```

| Part                     | Renders                  | Notes                                                                                           |
| ------------------------ | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `Separator` (horizontal) | `<hr>`                   | 1px tall, full width.                                                                           |
| `Separator` (vertical)   | `<div role="separator">` | 1px wide, stretches to the parent's height (`self-stretch`). Has `aria-orientation="vertical"`. |
| `Separator` with `label` | `<div role="separator">` | Horizontal only. A flex row with the label between two lines.                                   |

## Examples

### Vertical

`orientation="vertical"` stretches to the height of a flex parent. Use it between groups in toolbars, nav rows and stat strips; add margin with `mx-*` and trim the height with `my-*`.

Example `separator/vertical`: source in https://desyne.dev/docs/components/separator.md

### With label

`label` puts text in the line, for "or" dividers, dates in a feed or section titles. `labelPosition` moves it to the `start`, `center` (default) or `end`; the short side is 16px long. Labels only apply to horizontal separators.

Example `separator/label`: source in https://desyne.dev/docs/components/separator.md

### Dashed

`variant="dashed"` draws a dashed line in either orientation, with or without a label. It reads as lighter than a solid rule, which suits drafts, timelines and optional sections.

Example `separator/dashed`: source in https://desyne.dev/docs/components/separator.md

## Recipes

### Sign-in options

The classic "or continue with" divider between social sign-in buttons and an email form.

Example `separator/recipe-sign-in`: source in https://desyne.dev/docs/components/separator.md

### Stat strip

Vertical separators between equal-width stats. They stretch to the row's height automatically.

Example `separator/recipe-stats`: source in https://desyne.dev/docs/components/separator.md

## Accessibility

* A horizontal separator renders a native `<hr>`, which screen readers announce as a separator.
* A vertical separator renders a `<div>` with `role="separator"` and `aria-orientation="vertical"`, as `<hr>` is always horizontal.
* A labelled separator is a `<div role="separator">`. Screen readers generally don't read the content of a separator, so don't put essential information only in the label; "or" and dates are fine because the surrounding content carries the meaning.
* Separators aren't focusable. Inside a React Aria `Toolbar`, arrow-key navigation skips them.
* React Aria only forwards a filtered set of DOM props (ids, `aria-label` / `aria-labelledby` / `aria-describedby`, `data-*` and global attributes), so `aria-hidden` isn't passed through on an unlabelled separator (a labelled one forwards every prop). If a line is purely decorative, draw it with a `border-*` class on a neighboring element instead.

## Styling

### Data attributes

| Attribute               | Present when                                                                  |
| ----------------------- | ----------------------------------------------------------------------------- |
| `data-slot="separator"` | Always                                                                        |
| `data-orientation`      | `"horizontal"` or `"vertical"`. Always `"horizontal"` on labelled separators. |

### Customizing

* The line color is `bg-border`. Change it with a `bg-*` class, e.g. `bg-foreground/20`.
* Change thickness with `h-*` (horizontal) or `w-*` (vertical).
* For labelled separators, `className` goes on the flex row: change the label's text style there (`text-sm text-foreground`), or the line color with `before:bg-* after:bg-*`.

## API Reference

### Separator

<TypeTable
  type="{
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Direction of the line.&#x22; },
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Text in the line, e.g. \&#x22;or\&#x22;. Horizontal separators only.&#x22; },
  labelPosition: { type: '&#x22;start&#x22; | &#x22;center&#x22; | &#x22;end&#x22;', default: '&#x22;center&#x22;', description: &#x22;Where the label sits along the line.&#x22; },
  variant: { type: '&#x22;solid&#x22; | &#x22;dashed&#x22;', default: '&#x22;solid&#x22;', description: &#x22;Line style.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
  elementType: { type: &#x22;string&#x22;, description: 'Element to render instead of <hr> (e.g. &#x22;div&#x22;). Ignored when label is set (always a <div>).' },
  id: { type: &#x22;string&#x22;, description: &#x22;The element's id.&#x22; },
  slot: { type: &#x22;string | null&#x22;, description: &#x22;React Aria slot name. Ignored when label is set.&#x22; },
  style: { type: &#x22;CSSProperties&#x22;, description: &#x22;Inline styles.&#x22; },
}"
/>

Without a `label`, also accepts the props of React Aria's [`Separator`](https://react-aria.adobe.com/Separator): `aria-label`, `aria-labelledby`, `aria-describedby`, `data-*` attributes, `dir`, `lang`, `hidden` and mouse, pointer and touch event handlers. With a `label`, the separator is a plain `<div role="separator">` and every other prop (`id`, `style`, `aria-*`, `data-*`, event handlers, and so on) is forwarded to it unfiltered; only `elementType`, `slot` and `render` are dropped.

## Related

* [Card](/docs/components/card): `CardHeader` has a built-in inset separator.
* [Menu](/docs/components/menu): `MenuSeparator` between groups of menu items.
* [Item](/docs/components/item): `ItemSeparator` between list rows.
* [Toggle Button Group](/docs/components/toggle-button-group): grouped toolbar controls.

---

# Item

Source: https://desyne.dev/docs/components/item

> A flexible list row with media, a title, a quiet second line and trailing actions. Three surface variants, three sizes and four media styles; stack rows in an ItemGroup, divide them with ItemSeparator, or apply itemVariants to a link. API-compatible with shadcn's Item.

```tsx title="item/demo.tsx"
"use client";

import { DatabaseIcon, GlobeIcon, SmartphoneIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
} from "@/components/ui/item";

const rows = [
  { name: "Web SDK", meta: "2.4M events/day", icon: GlobeIcon, live: true },
  {
    name: "iOS SDK",
    meta: "v3.2.0 · 3 apps",
    icon: SmartphoneIcon,
    live: true,
  },
  {
    name: "Product database",
    meta: "Postgres replica",
    icon: DatabaseIcon,
    live: false,
  },
];

export default function ItemDemo() {
  return (
    <ItemGroup className="w-full max-w-sm">
      {rows.map((r) => (
        <Item key={r.name} size="sm" variant={r.live ? "default" : "muted"}>
          <ItemMedia variant="icon">
            <r.icon />
          </ItemMedia>
          <ItemContent>
            <ItemTitle>{r.name}</ItemTitle>
            <ItemDescription>{r.meta}</ItemDescription>
          </ItemContent>
          <ItemActions>
            {r.live ? (
              <Badge size="sm" variant="dot" color="success">
                Live
              </Badge>
            ) : (
              <Button variant="outline" size="xs">
                Connect
              </Button>
            )}
          </ItemActions>
        </Item>
      ))}
    </ItemGroup>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/item
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemSeparator,
  ItemTitle,
  itemVariants,
} from "@/components/ui/item";
```

```tsx
<ItemGroup>
  <Item>
    <ItemMedia variant="icon">
      <GlobeIcon />
    </ItemMedia>
    <ItemContent>
      <ItemTitle>Web SDK</ItemTitle>
      <ItemDescription>2.4M events/day</ItemDescription>
    </ItemContent>
    <ItemActions>
      <Button variant="outline" size="xs">Configure</Button>
    </ItemActions>
  </Item>
</ItemGroup>
```

<Callout title="Layout only, no collection behavior">
  `Item` is a styled `<div>` with no keyboard navigation or selection. It's
  ideal for static rows, settings lists and rows with their own buttons. For
  rows the user selects or navigates with arrow keys, use a
  [List Box](/docs/components/list-box) or [Grid List](/docs/components/grid-list).
</Callout>

### When to use

* Item: a row that shows an entity (a file, an integration, a person, a payment method) with optional actions. Works in cards, sidebars, popovers and pages.
* [Grid List](/docs/components/grid-list): an interactive list with selection, keyboard navigation or drag and drop.
* [List Box](/docs/components/list-box): a list of selectable options.
* [Table](/docs/components/table): when rows share several columns that users compare or sort.
* [Card](/docs/components/card): a larger, self-contained block with its own header and footer.

## Anatomy

```tsx
<ItemGroup>              {/* vertical stack of rows */}
  <Item>                 {/* row: variant, size */}
    <ItemMedia />        {/* icon tile, round mark, image or avatar */}
    <ItemContent>        {/* grows, truncates */}
      <ItemTitle />      {/* medium weight, can hold a badge */}
      <ItemDescription />{/* quiet second line */}
    </ItemContent>
    <ItemActions />      {/* trailing buttons, switches, badges */}
  </Item>
  <ItemSeparator />      {/* inset hairline between rows */}
</ItemGroup>
```

| Part              | Renders | Notes                                                                                               |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `ItemGroup`       | `<div>` | Flex column with a 2px gap. Carries `data-slot="item-group"`.                                       |
| `Item`            | `<div>` | Row. Flex, centered, 12px gap, rounded. Sets the `group/item` Tailwind group.                       |
| `ItemMedia`       | `<div>` | Leading visual. `icon`, `round` and `image` variants set the size and surface.                      |
| `ItemContent`     | `<div>` | Takes the remaining width (`flex-1 min-w-0`) so long text truncates instead of pushing actions out. |
| `ItemTitle`       | `<div>` | Single line, truncated. Flex with a gap, so an inline badge or icon sits next to the text.          |
| `ItemDescription` | `<p>`   | Muted, single line, truncated.                                                                      |
| `ItemActions`     | `<div>` | Trailing flex row that never shrinks.                                                               |
| `ItemSeparator`   | `<div>` | 1px line inset 12px from each side. Decorative.                                                     |

## Examples

### Variants

`default` is transparent, for rows inside a list, card or popover. `muted` fills the row to highlight it, for example the selected, unread or featured one. `outline` gives the row a bordered card surface so it can stand on its own.

Example `item/variants`: source in https://desyne.dev/docs/components/item.md

### Sizes

`size` sets the row padding: `sm` for dense lists and sidebars, `md` (default) for most lists, `lg` for spacious settings pages.

Example `item/sizes`: source in https://desyne.dev/docs/components/item.md

### Media

`icon` is a bordered 36px tile for icons and logo marks, `round` a 36px circle you color yourself, and `image` a 40px cover-fit thumbnail for an `<img>`. The `default` variant adds no size or surface, so any element fits, such as an [`Avatar`](/docs/components/avatar), or your own tinted tile.

Example `item/media`: source in https://desyne.dev/docs/components/item.md

### Actions and inline badges

`ItemActions` holds buttons, a menu trigger or a [`Switch`](/docs/components/switch). `ItemTitle` lays out its children in a row, so a [`Badge`](/docs/components/badge) sits next to the title. Label switches with the row's title via `aria-labelledby`, and give icon buttons an `aria-label` that names the row.

Example `item/actions`: source in https://desyne.dev/docs/components/item.md

### As a link

For rows that navigate, apply `itemVariants` to an `<a>` (or a Next.js or React Aria `Link`). The styles add a hover background and a keyboard focus ring when the element is a link or button. Use the `group-hover/item:` variant to animate the chevron.

Example `item/as-link`: source in https://desyne.dev/docs/components/item.md

### Group with separators

`ItemGroup` stacks rows with a 2px gap. Put it in a bordered container with `gap-0`, and place `ItemSeparator`s between rows for a divided list.

Example `item/group`: source in https://desyne.dev/docs/components/item.md

## Recipes

### Integrations

A connected-apps list: icon tiles, a "Not connected" badge in the title, and either a switch or a connect button per row.

Example `item/recipe-integrations`: source in https://desyne.dev/docs/components/item.md

### File list

Standalone `outline` rows with image thumbnails, a download button and a per-row [`Menu`](/docs/components/menu).

Example `item/recipe-files`: source in https://desyne.dev/docs/components/item.md

### Notifications

Unread rows use `variant="muted"` plus visually hidden "Unread" text, so the state isn't conveyed by color alone. Marking a row read switches it back to `default`.

Example `item/recipe-notifications`: source in https://desyne.dev/docs/components/item.md

## Accessibility

* `Item` and its parts are plain elements with no role. Wrap a list of rows in `<ul>`/`<li>`, or add `role="list"` / `role="listitem"`, when the list structure matters to screen reader users.
* `ItemTitle` is a `<div>`. If rows are sections with their own headings, put a heading element inside it.
* Don't attach `onClick` to an `Item` `<div>`. For navigation, render the row as a link with `itemVariants`; for selection, use a [Grid List](/docs/components/grid-list).
* Don't nest interactive elements inside a link row. If a row both navigates and has actions, use a stretched link in the title instead (see the [interactive cards](/docs/components/card#interactive-cards) pattern).
* Title and description truncate with an ellipsis. Truncated text is still read in full by screen readers; add a `title` attribute or a tooltip if sighted users need the full text too.
* Give controls in `ItemActions` names that identify the row, e.g. `aria-label="Download report.pdf"` rather than just "Download".

## Styling

### Data attributes

| Attribute                      | On                | Present when |
| ------------------------------ | ----------------- | ------------ |
| `data-slot="item-group"`       | `ItemGroup`       | Always       |
| `data-slot="item"`             | `Item`            | Always       |
| `data-slot="item-media"`       | `ItemMedia`       | Always       |
| `data-slot="item-content"`     | `ItemContent`     | Always       |
| `data-slot="item-title"`       | `ItemTitle`       | Always       |
| `data-slot="item-description"` | `ItemDescription` | Always       |
| `data-slot="item-actions"`     | `ItemActions`     | Always       |
| `data-slot="item-separator"`   | `ItemSeparator`   | Always       |

`Item` sets the `group/item` group, so children can react to row hover with `group-hover/item:…`. When `itemVariants` is applied to an `<a>` or `<button>`, it adds `hover:bg-muted/70`, a pointer (links) or default (buttons) cursor, left-aligned text for buttons and `focus-visible` ring styles.

### `itemVariants`

The `tailwind-variants` function behind `Item`. Use it to turn links, buttons or React Aria collection items into rows.

```tsx
import { itemVariants } from "@/components/ui/item";

<a href="/settings/profile" className={itemVariants({ size: "sm" })}>…</a>;
```

## API Reference

### Item

<TypeTable
  type="{
  variant: {
    type: '&#x22;default&#x22; | &#x22;muted&#x22; | &#x22;outline&#x22;',
    default: '&#x22;default&#x22;',
    description: &#x22;Surface: transparent, muted fill, or bordered card.&#x22;,
  },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Row padding.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### ItemMedia

<TypeTable
  type="{
  variant: {
    type: '&#x22;default&#x22; | &#x22;icon&#x22; | &#x22;round&#x22; | &#x22;image&#x22;',
    default: '&#x22;default&#x22;',
    description: &#x22;icon: bordered 36px tile (svg 16px). round: 36px circle (svg 16px). image: 40px rounded tile, child img fills and covers. default: no size or surface.&#x22;,
  },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### ItemGroup / ItemContent / ItemTitle / ItemActions / ItemSeparator

No extra props. Each accepts every prop of `<div>`.

### ItemDescription

No extra props. Accepts every prop of `<p>`.

### itemVariants

<TypeTable
  type="{
  variant: { type: &#x22;ItemProps['variant']&#x22;, default: '&#x22;default&#x22;' },
  size: { type: &#x22;ItemProps['size']&#x22;, default: '&#x22;md&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Grid List](/docs/components/grid-list): interactive rows with selection and keyboard navigation.
* [Card](/docs/components/card): a container for a group of items.
* [Avatar](/docs/components/avatar): media for rows about people.
* [Table](/docs/components/table): multi-column data.

---

# Kbd

Source: https://desyne.dev/docs/components/kbd

> Displays a keyboard key or shortcut as a keycap. Two sizes, icon support, and a KbdGroup for combinations and sequences. Built on React Aria's Keyboard, so inside a menu item it's linked to the item as its shortcut description.

```tsx title="kbd/demo.tsx"
"use client";

import { Kbd, KbdGroup } from "@/components/ui/kbd";

export default function KbdDemo() {
  return (
    <div className="flex flex-col items-center gap-4 text-muted-foreground text-sm">
      <KbdGroup>
        <Kbd>⌘</Kbd>
        <Kbd>⇧</Kbd>
        <Kbd>⌥</Kbd>
        <Kbd>⌃</Kbd>
      </KbdGroup>
      <p className="flex items-center gap-1.5">
        Press
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
        to open the command palette
      </p>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/kbd
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { Kbd, KbdGroup } from "@/components/ui/kbd";
```

```tsx
<KbdGroup>
  <Kbd>⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

<Callout title="Kbd displays shortcuts, it doesn't bind them">
  `Kbd` only renders the keycap. Register the actual shortcut with your own
  keydown listener or hotkey library, and keep the two in sync.
</Callout>

### When to use

* Kbd: to show which key or combination triggers an action, in help text, tooltips, menus, buttons and shortcut references.
* [`MenuShortcut`](/docs/components/menu): the menu's own unstyled, right-aligned shortcut text. Use `Kbd` in a menu item when you want keycaps instead.
* [Badge](/docs/components/badge): for labels and counts that aren't keys.
* Use the platform's symbols (⌘ ⇧ ⌥ ⌃ on macOS) or words (Ctrl, Shift, Alt) consistently, and switch between them per platform if your audience is mixed.

## Anatomy

```tsx
<KbdGroup>           {/* inline row of keys */}
  <Kbd>⌘</Kbd>       {/* one keycap */}
  <Kbd>
    <Icon />         {/* optional, auto-sized to 12px */}
    Enter
  </Kbd>
</KbdGroup>
```

| Part       | Renders           | Notes                                                                                                    |
| ---------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
| `Kbd`      | `<kbd dir="ltr">` | React Aria `Keyboard`. A keycap with a thicker bottom border. Not selectable and ignores pointer events. |
| `KbdGroup` | `<span>`          | Inline flex row with a 4px gap between keys and separators.                                              |
| Icon       | `<svg>`           | Any svg without a `size-*` class is sized to 12px.                                                       |

## Examples

### Sizes

`md` (22px tall) is the default for body text and help content. `sm` (18px) fits inside buttons, tooltips, menu items and inputs.

Example `kbd/sizes`: source in https://desyne.dev/docs/components/kbd.md

### Combinations and sequences

Put one `Kbd` per key in a `KbdGroup` for combinations. Add a "+" between keys when your UI uses word labels (Ctrl, Shift), and "then" for sequences such as <kbd>G</kbd> then <kbd>I</kbd>. A single `Kbd` with several symbols (⌘⇧P) is more compact for tight spaces.

Example `kbd/group`: source in https://desyne.dev/docs/components/kbd.md

### With icons

Icons are sized automatically. Pair icon-only keys with visually hidden text (`sr-only`) so the key's name is read out; symbol glyphs like ⌘ may be read inconsistently by screen readers.

Example `kbd/with-icon`: source in https://desyne.dev/docs/components/kbd.md

### In a tooltip

Show the shortcut next to the action's name in a [`Tooltip`](/docs/components/tooltip). The `light` tooltip variant keeps the keycap colors readable; on the default dark tooltip, override the keycap colors with a class.

Example `kbd/in-tooltip`: source in https://desyne.dev/docs/components/kbd.md

### In a menu

Inside a React Aria `MenuItem`, `Kbd` picks up the item's keyboard-shortcut slot: it gets an id and the item references it with `aria-describedby`, so screen readers announce the shortcut with the item. Add `ml-auto` to push it to the right.

Example `kbd/in-menu`: source in https://desyne.dev/docs/components/kbd.md

## Recipes

### Shortcut reference

A two-column cheat sheet: a description list per section, with combinations and sequences.

Example `kbd/recipe-shortcuts`: source in https://desyne.dev/docs/components/kbd.md

### Search trigger

A search button that advertises <kbd>⌘</kbd> <kbd>K</kbd> and a window keydown listener that handles both ⌘K and Ctrl+K.

Example `kbd/recipe-search-trigger`: source in https://desyne.dev/docs/components/kbd.md

## Accessibility

* `Kbd` renders the semantic `<kbd>` element with `dir="ltr"`, so key combinations keep their order in right-to-left layouts.
* Screen readers read the text inside. Symbols like ⌘, ⇧ and ⌥ are read inconsistently across screen readers (by Unicode name, or skipped); include readable text (`<span className="sr-only">Command</span>`) where the shortcut matters, or use words.
* Inside a menu item, the shortcut is exposed as the item's description via `aria-describedby`. Elsewhere, it's plain inline text.
* Decorative separators such as "+" can be hidden with `aria-hidden` so the combination reads as the key names only.
* A shortcut must never be the only way to reach an action. Keep a visible, clickable control.

## Styling

### Data attributes

| Attribute               | On         | Present when |
| ----------------------- | ---------- | ------------ |
| `data-slot="kbd"`       | `Kbd`      | Always       |
| `data-slot="kbd-group"` | `KbdGroup` | Always       |

### Customizing

The keycap uses `bg-muted`, `text-muted-foreground` and a `border-b-2` bottom edge. On a colored surface, such as a solid button, override them:

```tsx
<Button>
  Publish
  <Kbd size="sm" className="border-white/20 bg-white/10 text-inherit">⌘↵</Kbd>
</Button>
```

## API Reference

### Kbd

<TypeTable
  type="{
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Height 18px or 22px, with matching min-width, padding and font size.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Key label, symbol or icon.&#x22; },
}"
/>

Also accepts every prop of React Aria's `Keyboard` (the props of `<kbd>`).

### KbdGroup

No extra props. Accepts every prop of `<span>`.

## Related

* [Menu](/docs/components/menu): menu items with shortcuts.
* [Tooltip](/docs/components/tooltip): show shortcuts next to icon buttons.
* [Button](/docs/components/button): buttons with a keyboard hint.
* [Command Palette](/docs/components/command-palette): the usual target of ⌘K.

---

# Chart

Source: https://desyne.dev/docs/components/chart

> Themed building blocks for Recharts. ChartContainer makes a chart responsive, maps a config of labels, colors and icons to CSS variables that follow light and dark mode, and restyles Recharts' grid, axes and cursors with your tokens; ChartTooltipContent and ChartLegendContent render matching tooltips and legends. You compose the charts with Recharts itself.

```tsx title="chart/demo.tsx"
"use client";

import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
import {
  type ChartConfig,
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/ui/chart";

const data = [
  { month: "January", desktop: 186, mobile: 80 },
  { month: "February", desktop: 305, mobile: 200 },
  { month: "March", desktop: 237, mobile: 120 },
  { month: "April", desktop: 73, mobile: 190 },
  { month: "May", desktop: 209, mobile: 130 },
  { month: "June", desktop: 214, mobile: 140 },
];

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

export default function ChartDemo() {
  return (
    <ChartContainer config={config} className="min-h-[200px] w-full max-w-lg">
      <BarChart data={data}>
        <CartesianGrid vertical={false} />
        <XAxis
          dataKey="month"
          tickLine={false}
          tickMargin={10}
          axisLine={false}
          tickFormatter={(v) => v.slice(0, 3)}
        />
        <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>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/chart
```

npm dependencies (installed by the CLI): recharts.

Charts are built with [Recharts](https://recharts.github.io) 3, which the install adds as a dependency.

## Usage

```tsx
import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
import {
  type ChartConfig,
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/ui/chart";
```

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

<ChartContainer config={config} className="h-[240px] w-full">
  <BarChart data={data}>
    <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>
```

<Callout title="Config keys become CSS variables">
  Every key in `config` with a `color` or `theme` becomes a `--color-<key>`
  variable scoped to that chart's container, so series use
  `fill="var(--color-desktop)"`. The same keys give the tooltip and legend
  their labels and icons. The variables only exist inside the container; for
  a custom legend rendered outside it, use the config's color value directly.
</Callout>

### When to use

* Chart: to show trends, comparisons or composition over many data points.
* [Meter](/docs/components/meter) or [Progress Bar](/docs/components/progress-bar): a single value against a known range.
* [Card](/docs/components/card) with a large number: when the one figure matters more than its shape. Add a small sparkline as in the [KPI recipe](#kpi-card-with-sparkline).
* [Table](/docs/components/table): when users need exact values or will compare individual rows.
* Pick the chart for the question: bars to compare categories, lines for trends over time, stacked areas for how parts add up over time, and pies or donuts only for a few parts of one whole.

## Anatomy

```tsx
<ChartContainer config={config}>          {/* responsive wrapper + <style> with --color-* */}
  <BarChart data={data}>                  {/* any Recharts chart */}
    <CartesianGrid />                     {/* restyled to the border token */}
    <XAxis />                             {/* tick text uses muted-foreground */}
    <ChartTooltip                         {/* = Recharts Tooltip */}
      content={<ChartTooltipContent />}   {/* themed tooltip body */}
    />
    <ChartLegend                          {/* = Recharts Legend */}
      content={<ChartLegendContent />}    {/* themed legend body */}
    />
    <Bar dataKey="desktop" fill="var(--color-desktop)" />
  </BarChart>
</ChartContainer>
```

| Part                  | Renders                                     | Notes                                                                                                                                                    |
| --------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChartContainer`      | `<div>` › `<style>` + `ResponsiveContainer` | Provides the config through context, writes the `--color-*` variables for light and `.dark`, and sizes the chart to the div. Defaults to `aspect-video`. |
| `ChartTooltip`        | Recharts `Tooltip`                          | Re-exported unchanged. Pass `content={<ChartTooltipContent />}`.                                                                                         |
| `ChartTooltipContent` | `<div>`                                     | Label plus one row per series: indicator, config label, and the value formatted with `toLocaleString()`.                                                 |
| `ChartLegend`         | Recharts `Legend`                           | Re-exported unchanged. Pass `content={<ChartLegendContent />}`.                                                                                          |
| `ChartLegendContent`  | `<div>`                                     | A centered row of swatches (or config icons) with config labels.                                                                                         |
| `ChartConfig`         | type                                        | `Record<key, { label?, icon?, color? } or { label?, icon?, theme: { light, dark } }>`.                                                                   |
| `useChart`            | hook                                        | Returns `{ config }` inside a `ChartContainer`, for custom tooltip or legend content.                                                                    |

## Examples

### Bar

Bars compare categories. Set a `radius` for rounded tops, hide the axis lines and use `vertical={false}` on the grid for a quiet background. The hero example above adds a legend below the chart.

```tsx title="chart/demo.tsx"
"use client";

import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
import {
  type ChartConfig,
  ChartContainer,
  ChartLegend,
  ChartLegendContent,
  ChartTooltip,
  ChartTooltipContent,
} from "@/components/ui/chart";

const data = [
  { month: "January", desktop: 186, mobile: 80 },
  { month: "February", desktop: 305, mobile: 200 },
  { month: "March", desktop: 237, mobile: 120 },
  { month: "April", desktop: 73, mobile: 190 },
  { month: "May", desktop: 209, mobile: 130 },
  { month: "June", desktop: 214, mobile: 140 },
];

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

export default function ChartDemo() {
  return (
    <ChartContainer config={config} className="min-h-[200px] w-full max-w-lg">
      <BarChart data={data}>
        <CartesianGrid vertical={false} />
        <XAxis
          dataKey="month"
          tickLine={false}
          tickMargin={10}
          axisLine={false}
          tickFormatter={(v) => v.slice(0, 3)}
        />
        <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>
  );
}
```

### Horizontal bar

Set `layout="vertical"` on `BarChart`, make the `YAxis` a `category` axis and the `XAxis` a hidden `number` axis. Horizontal bars suit long category labels like page paths or names.

Example `chart/bar-horizontal`: source in https://desyne.dev/docs/components/chart.md

### Stacked bar

Give bars the same `stackId` to stack them. Round only the outer corners with a four-value `radius`, so the stack reads as one bar.

Example `chart/bar-stacked`: source in https://desyne.dev/docs/components/chart.md

### Area

An area chart emphasizes volume over time. A `linearGradient` in `<defs>` that fades the series color gives the fill depth; reference it with `fill="url(#id)"`.

Example `chart/area`: source in https://desyne.dev/docs/components/chart.md

### Stacked area

Stack areas with a shared `stackId` to show how parts add up to a total over time. Use a `tickFormatter` on the `YAxis` to keep large numbers short.

Example `chart/area-stacked`: source in https://desyne.dev/docs/components/chart.md

### Line

Lines are best for trends and comparing a few series. Use `dot={false}` for dense data and `type="monotone"` for smooth curves that don't overshoot. Colors can come from any token, such as `var(--destructive)` for a critical series.

Example `chart/line`: source in https://desyne.dev/docs/components/chart.md

### Pie

For a pie, put the color on each data row as `fill: "var(--color-<name>)"` and pass `nameKey` so the tooltip and legend look up each slice's label in the config. `hideLabel` drops the tooltip's heading, which isn't meaningful for a single slice.

Example `chart/pie`: source in https://desyne.dev/docs/components/chart.md

### Donut with a center label

`innerRadius` turns a pie into a donut. A Recharts `Label` with a `content` function draws the total in the middle using `fill-foreground` and `fill-muted-foreground`, so it follows the theme.

Example `chart/donut`: source in https://desyne.dev/docs/components/chart.md

### Tooltip

`ChartTooltipContent` shows a label and one row per series. `indicator` picks a `dot` (default), `line` or `dashed` swatch; with a single series and `line` or `dashed`, the label moves into the row. `hideLabel` and `hideIndicator` remove those parts. These previews use Recharts' `defaultIndex` to show the tooltip without hovering.

Example `chart/tooltip`: source in https://desyne.dev/docs/components/chart.md

For custom content, `labelFormatter(label, payload)` replaces the heading and `formatter(value, name, item, index)` replaces an entire row. See the [KPI recipe](#kpi-card-with-sparkline) for currency formatting.

### Legend and icons

`ChartLegendContent` renders each series' config `label` with a color swatch, or the config `icon` when one is set (the icon also replaces the tooltip indicator). Place the legend above the chart with `verticalAlign="top"` on both `ChartLegend` and `ChartLegendContent`.

Example `chart/legend`: source in https://desyne.dev/docs/components/chart.md

### Theming and dark mode

`color` accepts any CSS color, including tokens like `var(--chart-1)` which already switch with the theme. For colors that need a different value per mode, use `theme: { light, dark }`; the container writes the dark values under the `.dark` class. Toggle the site theme to see this chart change.

Example `chart/theme`: source in https://desyne.dev/docs/components/chart.md

The default palette is `--chart-1` to `--chart-5` (indigo, teal, amber, pink, sky), defined for light and dark mode in the theme. Override those variables to re-color every chart at once.

## Recipes

### KPI card with sparkline

A [`Card`](/docs/components/card) with a headline figure, a trend badge and an axis-less area sparkline flush with the card's bottom edge. The tooltip uses `labelFormatter` and `formatter` to show the date and a currency value.

Example `chart/recipe-kpi`: source in https://desyne.dev/docs/components/chart.md

### Switchable metric

A segmented [`ToggleButtonGroup`](/docs/components/toggle-button-group) in `CardAction` switches which series the bar chart shows, and the title shows the matching total. `minTickGap` thins the date ticks on narrow screens.

Example `chart/recipe-interactive`: source in https://desyne.dev/docs/components/chart.md

### Traffic sources

A small donut next to a custom legend list with percentages. The list sits outside `ChartContainer`, so its swatches use the config's `color` values rather than the scoped `--color-*` variables.

Example `chart/recipe-traffic-sources`: source in https://desyne.dev/docs/components/chart.md

## Accessibility

* Recharts 3 turns on its `accessibilityLayer` by default: the chart surface is focusable (`tabIndex={0}`) with `role="application"`, and in bar, line and area charts <kbd>←</kbd> and <kbd>→</kbd> move the tooltip between data points. Pass `accessibilityLayer={false}` to opt out.
* Charts are visual. Always state the key takeaway in text nearby (a title, a total, a delta), and offer the underlying numbers as a [table](/docs/components/table) or download for anything important.
* Don't rely on color alone to tell series apart. Use a legend with clear labels, direct labels, icons, or different line styles (for example `strokeDasharray`).
* Keep enough contrast between adjacent series and against the background in both themes; the default `--chart-*` palette is tuned for this.
* Tooltips appear on hover and keyboard focus only. Put anything essential in the visible chart or surrounding text.

### Keyboard

With the default accessibility layer:

| Key                         | Action                                                                          |
| --------------------------- | ------------------------------------------------------------------------------- |
| <kbd>Tab</kbd>              | Moves focus to the chart                                                        |
| <kbd>←</kbd> / <kbd>→</kbd> | Moves the active tooltip to the previous or next data point (axis-based charts) |

## Styling

### Data attributes

| Attribute           | On               | Present when                                                                                                      |
| ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `data-slot="chart"` | `ChartContainer` | Always                                                                                                            |
| `data-chart`        | `ChartContainer` | Always. A unique id (`chart-<id>`) that scopes the generated `--color-*` variables. Pass `id` for a stable value. |

### CSS variables

| Variable                  | Defined for                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `--color-<key>`           | Every config key with a `color` or `theme` value, scoped to `[data-chart=…]`, with dark values under `.dark` |
| `--chart-1` … `--chart-5` | The theme's default chart palette (global)                                                                   |

Avoid config keys that match Tailwind color names used inside the chart (like `border` or `muted`), since the generated `--color-<key>` would shadow them within the container.

### Theme overrides

`ChartContainer` restyles Recharts' default greys to your tokens: axis tick text uses `muted-foreground`; the grid, polar grid, reference lines and line cursor use `border`; the bar cursor and radial bar backgrounds use `muted`. It also removes white strokes on dots and sectors and hides focus outlines on the SVG layers. Size the chart with `className`: the default is `aspect-video`; use `aspect-auto h-[240px]` for a fixed height, or `aspect-square` for pies.

## API Reference

### ChartContainer

<TypeTable
  type="{
  config: { type: &#x22;ChartConfig&#x22;, description: &#x22;Labels, icons and colors per data key. Required.&#x22; },
  children: { type: &#x22;ReactElement&#x22;, description: &#x22;A single Recharts chart (BarChart, LineChart, AreaChart, PieChart, …).&#x22; },
  id: { type: &#x22;string&#x22;, description: &#x22;Stable id for the data-chart attribute. A unique id is generated when omitted.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Sizing and extra styles. Defaults to aspect-video; use aspect-auto with a height to override.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### ChartConfig

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Name shown in the tooltip and legend.&#x22; },
  icon: { type: &#x22;ComponentType&#x22;, description: &#x22;Replaces the swatch in the legend and the indicator in the tooltip.&#x22; },
  color: { type: &#x22;string&#x22;, description: &#x22;Any CSS color or variable. Mutually exclusive with theme.&#x22; },
  theme: { type: &#x22;{ light: string; dark: string }&#x22;, description: &#x22;Separate colors for light and dark (.dark) mode. Mutually exclusive with color.&#x22; },
}"
/>

### ChartTooltipContent

Recharts passes `active`, `payload` and `label` automatically when used as `content`.

<TypeTable
  type="{
  indicator: { type: '&#x22;dot&#x22; | &#x22;line&#x22; | &#x22;dashed&#x22;', default: '&#x22;dot&#x22;', description: &#x22;Swatch style for each row.&#x22; },
  hideLabel: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Hides the heading (e.g. the x-axis value).&#x22; },
  hideIndicator: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Hides the swatches.&#x22; },
  labelKey: { type: &#x22;string&#x22;, description: &#x22;Config key (or payload field holding one) to use for the heading instead of the axis label.&#x22; },
  nameKey: { type: &#x22;string&#x22;, description: &#x22;Config key (or payload field holding one) for each row's label, e.g. the name field of pie data.&#x22; },
  labelFormatter: { type: &#x22;(label: ReactNode, payload: PayloadItem[]) => ReactNode&#x22;, description: &#x22;Custom heading.&#x22; },
  formatter: { type: &#x22;(value: unknown, name: string | number | undefined, item: PayloadItem, index: number) => ReactNode&#x22;, description: &#x22;Custom content for an entire row, replacing indicator, label and value.&#x22; },
  color: { type: &#x22;string&#x22;, description: &#x22;Overrides every indicator's color.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the tooltip box.&#x22; },
  active: { type: &#x22;boolean&#x22;, description: &#x22;Set by Recharts.&#x22; },
  payload: { type: &#x22;PayloadItem[]&#x22;, description: &#x22;Set by Recharts.&#x22; },
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Set by Recharts.&#x22; },
}"
/>

### ChartLegendContent

<TypeTable
  type="{
  nameKey: { type: &#x22;string&#x22;, description: &#x22;Config key (or payload field holding one) for each entry, e.g. the name field of pie data.&#x22; },
  hideIcon: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Always show the color swatch, even when the config has an icon.&#x22; },
  verticalAlign: { type: '&#x22;top&#x22; | &#x22;middle&#x22; | &#x22;bottom&#x22;', default: '&#x22;bottom&#x22;', description: &#x22;Adds spacing below (top) or above (otherwise) the legend. Match the Legend's own verticalAlign.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the legend row.&#x22; },
  payload: { type: &#x22;PayloadItem[]&#x22;, description: &#x22;Set by Recharts.&#x22; },
}"
/>

Only entries whose key is in the config get a label.

### ChartTooltip / ChartLegend

Recharts' [`Tooltip`](https://recharts.github.io/en-US/api/Tooltip) and [`Legend`](https://recharts.github.io/en-US/api/Legend), re-exported unchanged. Useful props include `cursor`, `defaultIndex` and `content` on the tooltip, and `verticalAlign`, `align` and `content` on the legend.

### useChart

```tsx
const { config } = useChart();
```

Reads the nearest `ChartContainer`'s config. Throws when used outside one.

## Related

* [Card](/docs/components/card): the usual frame for a chart with a title and summary.
* [Meter](/docs/components/meter): a single value within a range.
* [Toggle Button Group](/docs/components/toggle-button-group): switch series or time ranges.
* [Table](/docs/components/table): the accessible alternative for exact values.

---

# Carousel

Source: https://desyne.dev/docs/components/carousel

> A swipeable, scrollable set of slides built on Embla Carousel. Horizontal or vertical, one or many slides per view, looping, previous and next buttons that disable at the ends, arrow-key navigation, WAI-ARIA labels and slide announcements, and full access to the Embla API for counters, dots, thumbnails and autoplay.

```tsx title="carousel/demo.tsx"
"use client";

import { Card, CardContent } from "@/components/ui/card";
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel";

const slides = [
  {
    title: "Dashboards",
    text: "Every metric in one place.",
    tone: "from-chart-1/25",
  },
  {
    title: "Alerts",
    text: "Know before your users do.",
    tone: "from-chart-2/25",
  },
  {
    title: "Reports",
    text: "Scheduled PDFs for the board.",
    tone: "from-chart-3/25",
  },
  {
    title: "Integrations",
    text: "Connect 40+ data sources.",
    tone: "from-chart-4/25",
  },
  {
    title: "Audit log",
    text: "Every change, attributed.",
    tone: "from-chart-5/25",
  },
];

export default function CarouselDemo() {
  return (
    <Carousel aria-label="Product features" className="w-full max-w-xs">
      <CarouselContent>
        {slides.map((s) => (
          <CarouselItem key={s.title}>
            <Card className={`bg-gradient-to-br ${s.tone} to-card`}>
              <CardContent className="flex aspect-square flex-col justify-end gap-1 p-6">
                <span className="font-semibold text-2xl">{s.title}</span>
                <span className="text-muted-foreground text-sm">{s.text}</span>
              </CardContent>
            </Card>
          </CarouselItem>
        ))}
      </CarouselContent>
      <CarouselPrevious />
      <CarouselNext />
    </Carousel>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/carousel
```

npm dependencies (installed by the CLI): embla-carousel-react, lucide-react.

The install adds `embla-carousel-react` as a dependency.

## Usage

```tsx
import {
  Carousel,
  type CarouselApi,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
  useCarousel,
} from "@/components/ui/carousel";
```

```tsx
<Carousel aria-label="Product photos">
  <CarouselContent>
    <CarouselItem>…</CarouselItem>
    <CarouselItem>…</CarouselItem>
    <CarouselItem>…</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

<Callout title="Embla does the scrolling">
  `Carousel` passes `opts` and `plugins` straight to Embla's
  `useEmblaCarousel`, so every [Embla option](https://www.embla-carousel.com/api/options/)
  (`loop`, `align`, `slidesToScroll`, `dragFree`, `startIndex`, …) and plugin
  works. `orientation` sets Embla's `axis` for you.
</Callout>

### When to use

* Carousel: a small set of peer items where showing one (or a few) at a time saves space, such as product photos, testimonials or onboarding steps.
* [Tabs](/docs/components/tabs): when each panel has a name the user should pick directly.
* A plain grid or scrolling row: when users need to scan or compare everything. Content hidden in later slides is often never seen.
* Avoid autoplay for important content, and never put the only copy of critical information in a carousel.

## Anatomy

```tsx
<Carousel>               {/* <section aria-roledescription="carousel" aria-label>, Embla + context */}
  <CarouselContent>      {/* viewport (overflow-hidden) › flex track (id for aria-controls) */}
    <CarouselItem />     {/* role="group" aria-roledescription="slide" aria-label="1 of 5" */}
  </CarouselContent>
  <CarouselPrevious />   {/* Button, disabled at the start */}
  <CarouselNext />       {/* Button, disabled at the end */}
  {/* visually hidden aria-live="polite" region, rendered for you */}
</Carousel>
```

| Part               | Renders                             | Notes                                                                                                                                                                                                                 |
| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Carousel`         | `<section>`                         | Creates the Embla instance, provides context, names the region, and handles the arrow keys for anything focused inside. Also renders the visually hidden live region. `relative`, so the buttons position against it. |
| `CarouselContent`  | `<div>` › `<div>`                   | The outer div is Embla's viewport (`overflow-hidden`); the inner div is the flex track and receives your `className` and props. A negative margin offsets the items' gutter.                                          |
| `CarouselItem`     | `<div role="group">`                | One slide, labelled with its position ("2 of 5") automatically. `basis-full` by default, with a 16px leading gutter (`pl-4`, or `pt-4` vertically).                                                                   |
| `CarouselPrevious` | [`Button`](/docs/components/button) | Round `outline` icon button placed outside the left (or top) edge, with `aria-controls` pointing at the track. Disabled when Embla can't scroll back.                                                                 |
| `CarouselNext`     | [`Button`](/docs/components/button) | Same, on the right (or bottom) edge.                                                                                                                                                                                  |
| `useCarousel`      | hook                                | Context for custom controls: `api`, `scrollPrev`, `scrollNext`, `canScrollPrev`, `canScrollNext`, `orientation`, `contentId`.                                                                                         |

## Examples

### Multiple slides per view

Set a `basis-*` class on `CarouselItem` to show several slides at once, with responsive variants like `md:basis-1/3`. `opts={{ align: "start" }}` aligns snaps to the leading edge instead of centering them.

Example `carousel/multiple`: source in https://desyne.dev/docs/components/carousel.md

### Spacing

The gap between slides is the items' leading padding, balanced by a negative margin on the content. Change both together: `-ml-2` on `CarouselContent` and `pl-2` on each `CarouselItem` for an 8px gap.

Example `carousel/spacing`: source in https://desyne.dev/docs/components/carousel.md

### Vertical

`orientation="vertical"` scrolls on the y axis and moves the buttons above and below. Give `CarouselContent` a fixed height, and use `-mt-*` / `pt-*` for spacing. The keyboard follows the axis: <kbd>↑</kbd> and <kbd>↓</kbd> move between slides in a vertical carousel.

Example `carousel/vertical`: source in https://desyne.dev/docs/components/carousel.md

### Loop

`opts={{ loop: true }}` wraps from the last slide to the first. The previous and next buttons never disable.

Example `carousel/loop`: source in https://desyne.dev/docs/components/carousel.md

### Controls inside

The buttons are absolutely positioned outside the carousel by default, which needs horizontal room. Override the position with `className` to place them over the slides; tailwind-merge replaces the default offsets.

Example `carousel/controls-inside`: source in https://desyne.dev/docs/components/carousel.md

### API and slide counter

Pass `setApi` to receive the Embla API once it's ready. Subscribe to its `select` and `reInit` events to track the current slide, and unsubscribe in the effect cleanup. The carousel already announces slide changes, so a visible counter like this one is `aria-hidden` rather than a second live region.

Example `carousel/api`: source in https://desyne.dev/docs/components/carousel.md

### Dot indicators

With the API, `scrollTo(index)` jumps to a slide and `selectedScrollSnap()` tells you which dot is active. Mark the active dot with `aria-current` and label each dot with its slide number.

Example `carousel/dots`: source in https://desyne.dev/docs/components/carousel.md

### Autoplay

Call `api.scrollNext()` on an interval, with `loop` so it wraps. Pause while the pointer or focus is inside, provide a visible pause button, and start paused when the user prefers reduced motion. Pass `announce={!playing}` so the live region stays quiet while slides rotate on their own. Embla's [autoplay plugin](https://www.embla-carousel.com/plugins/autoplay/) (`embla-carousel-autoplay`, installed separately) can be passed through `plugins` instead.

Example `carousel/autoplay`: source in https://desyne.dev/docs/components/carousel.md

## Recipes

### Testimonials

Two cards per view on larger screens, one on mobile, with looping. Cards use `h-full` so every slide matches the tallest.

Example `carousel/recipe-testimonials`: source in https://desyne.dev/docs/components/carousel.md

### Product gallery with thumbnails

Two synced carousels: selecting a slide in the main one scrolls the thumbnail strip, and pressing a thumbnail calls `scrollTo` on the main API. The strip uses `dragFree` and `containScroll: "keepSnaps"`, and `announce={false}` so only the main carousel speaks.

Example `carousel/recipe-gallery`: source in https://desyne.dev/docs/components/carousel.md

### Onboarding steps

A step-by-step flow inside a [`Card`](/docs/components/card). `watchDrag: false` disables swiping so users move only with the buttons, and a custom footer reads `useCarousel()` to render Back, Continue and a step counter. The footer counter is the live region, so the carousel's own is turned off with `announce={false}`, and each slide keeps a custom `aria-label` ("Step 2 of 3").

Example `carousel/recipe-onboarding`: source in https://desyne.dev/docs/components/carousel.md

## Accessibility

Follows the [WAI-ARIA carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) out of the box:

* `Carousel` renders a `<section>` with `aria-roledescription="carousel"` and an accessible name. Pass `aria-label` (for example "Product photos") or `aria-labelledby`; otherwise the `label` prop is used, which defaults to "Carousel". Always give a descriptive name when a page has more than one carousel.
* Each `CarouselItem` has `role="group"`, `aria-roledescription="slide"` and a position label such as "2 of 5", computed from Embla's slide list and updated on `reInit`. Pass `aria-label` or `aria-labelledby` on an item to replace it, or `formatSlideLabel` on `Carousel` to change the wording for every slide (for example to translate it).
* A visually hidden `aria-live="polite"` region announces the selection when it changes: "Slide 3 of 5", or "Slides 4 to 6 of 9" when several slides share a snap. Nothing is announced on first render. Change the text with `formatAnnouncement`, and set `announce={false}` while auto-rotating or when you render your own live counter.
* The previous and next buttons are labelled "Previous slide" and "Next slide", reference the slide track with `aria-controls`, and are disabled at the ends (unless `loop` is on). Pass `aria-label` to override the labels.
* Arrow keys follow the orientation: <kbd>←</kbd> / <kbd>→</kbd> when horizontal (swapped when `opts.direction` is `"rtl"` or the carousel sits in a right-to-left context), <kbd>↑</kbd> / <kbd>↓</kbd> when vertical. They work whenever focus is inside the carousel, run in the capture phase and prevent the default, but are ignored while typing in an input, textarea, select or contenteditable element.
* Slides outside the viewport stay in the DOM and in the tab order. Keep slide content focusable only when it's useful, and consider `inert` on off-screen slides for heavy interactive content.
* Autoplay must have a visible pause control, pause on hover and focus, and respect `prefers-reduced-motion` (see [Autoplay](#autoplay)).

### Keyboard

| Key                                 | Action                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
| <kbd>Tab</kbd>                      | Moves focus to the previous and next buttons and to focusable content in the slides              |
| <kbd>←</kbd> / <kbd>→</kbd>         | Horizontal: previous / next slide while focus is inside the carousel (reversed in right-to-left) |
| <kbd>↑</kbd> / <kbd>↓</kbd>         | Vertical: previous / next slide while focus is inside the carousel                               |
| <kbd>Space</kbd> / <kbd>Enter</kbd> | Activates the focused previous or next button                                                    |

## Styling

### Data attributes

| Attribute                        | On                      | Present when                           |
| -------------------------------- | ----------------------- | -------------------------------------- |
| `data-slot="carousel"`           | `Carousel`              | Always                                 |
| `data-orientation`               | `Carousel`              | Always, `"horizontal"` or `"vertical"` |
| `data-slot="carousel-content"`   | viewport div            | Always                                 |
| `data-slot="carousel-item"`      | `CarouselItem`          | Always                                 |
| `data-slot="carousel-previous"`  | `CarouselPrevious`      | Always                                 |
| `data-slot="carousel-next"`      | `CarouselNext`          | Always                                 |
| `data-slot="carousel-announcer"` | live region             | `announce` is on                       |
| `data-disabled`                  | previous / next buttons | The carousel can't scroll that way     |

The buttons also carry the usual [`Button`](/docs/components/button#data-attributes) state attributes (`data-hovered`, `data-pressed`, `data-focus-visible`).

### Customizing

* Slide width: `basis-*` on `CarouselItem`.
* Gap: `-ml-*` on `CarouselContent` and `pl-*` on `CarouselItem` (or `-mt-*` / `pt-*` vertically).
* Buttons: `variant`, `size` and `className` on `CarouselPrevious` / `CarouselNext`. They're `outline` and `icon-sm` by default, rounded, with the arrow rotated 90° in vertical mode.
* Height (vertical): a fixed `h-*` on `CarouselContent`.

## API Reference

### Carousel

<TypeTable
  type="{
  opts: { type: &#x22;EmblaOptionsType&#x22;, description: &#x22;Embla options (loop, align, slidesToScroll, dragFree, containScroll, startIndex, watchDrag, duration, …). axis is set from orientation.&#x22; },
  plugins: { type: &#x22;EmblaPluginType[]&#x22;, description: &#x22;Embla plugins such as embla-carousel-autoplay.&#x22; },
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Scroll axis and button placement.&#x22; },
  setApi: { type: &#x22;(api: CarouselApi) => void&#x22;, description: &#x22;Receives the Embla API once it's initialized.&#x22; },
  label: { type: &#x22;string&#x22;, default: '&#x22;Carousel&#x22;', description: &#x22;Accessible name used when neither aria-label nor aria-labelledby is passed.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name for the carousel region. Takes precedence over label.&#x22; },
  announce: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Announce the selected slide in a polite live region when it changes. Turn off while auto-rotating.&#x22; },
  formatSlideLabel: { type: &#x22;(index: number, total: number) => string&#x22;, default: '&#x22;2 of 5&#x22;', description: &#x22;Accessible name of each slide. index is 0-based. Ignored for items with their own aria-label.&#x22; },
  formatAnnouncement: { type: &#x22;(selection: { from: number; to: number; total: number }) => string&#x22;, default: '&#x22;Slide 2 of 5&#x22;', description: &#x22;Live-region text. from and to are 0-based and differ when several slides share a snap.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes for the <section>.&#x22; },
}"
/>

Also accepts every prop of `<section>` (typed as `<div>` props), such as `onMouseEnter` and `onFocus`.

### CarouselContent / CarouselItem

No extra props. `CarouselContent` passes `className` and all props to the inner track `<div>`, which gets a generated `id` (used by the buttons' `aria-controls`) unless you pass one. `CarouselItem` accepts every prop of `<div>`, including `ref`; its `aria-label` defaults to the slide position.

### CarouselPrevious / CarouselNext

A [`Button`](/docs/components/button). Accepts every button prop; `onPress`, `isDisabled` and `aria-label` are set for you but can be overridden.

<TypeTable
  type="{
  variant: { type: &#x22;ButtonProps['variant']&#x22;, default: '&#x22;outline&#x22;' },
  size: { type: &#x22;ButtonProps['size']&#x22;, default: '&#x22;icon-sm&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Merged with the default absolute positioning.&#x22; },
}"
/>

### useCarousel

Call inside `Carousel` to build custom controls. Throws outside one.

<TypeTable
  type="{
  api: { type: &#x22;CarouselApi&#x22;, description: &#x22;The Embla API, or undefined before initialization.&#x22; },
  scrollPrev: { type: &#x22;() => void&#x22;, description: &#x22;Scrolls to the previous snap.&#x22; },
  scrollNext: { type: &#x22;() => void&#x22;, description: &#x22;Scrolls to the next snap.&#x22; },
  canScrollPrev: { type: &#x22;boolean&#x22;, description: &#x22;Updated on select and reInit.&#x22; },
  canScrollNext: { type: &#x22;boolean&#x22;, description: &#x22;Updated on select and reInit.&#x22; },
  orientation: { type: '&#x22;horizontal&#x22; | &#x22;vertical&#x22;' },
  opts: { type: &#x22;EmblaOptionsType&#x22;, description: &#x22;The options passed to Carousel.&#x22; },
  carouselRef: { type: &#x22;(node: HTMLElement | null) => void&#x22;, description: &#x22;Embla's viewport ref, used by CarouselContent.&#x22; },
  contentId: { type: &#x22;string&#x22;, description: &#x22;id of the slide track, for aria-controls on custom buttons.&#x22; },
  slideNodes: { type: &#x22;HTMLElement[]&#x22;, description: &#x22;Embla's slide elements, updated on init and reInit.&#x22; },
  announce: { type: &#x22;boolean&#x22;, description: &#x22;Whether the built-in live region is on.&#x22; },
}"
/>

### CarouselApi

The Embla instance type. Common methods: `scrollNext()`, `scrollPrev()`, `scrollTo(index)`, `selectedScrollSnap()`, `scrollSnapList()`, `canScrollNext()`, `canScrollPrev()`, `slidesInView()`, `on(event, fn)` and `off(event, fn)`. See the [Embla API](https://www.embla-carousel.com/api/methods/).

## Related

* [Tabs](/docs/components/tabs): named panels the user picks directly.
* [Card](/docs/components/card): the usual slide surface.
* [Button](/docs/components/button): the base of the previous and next controls.
* [Pagination](/docs/components/pagination): paging through large result sets.

---

# Timeline

Source: https://desyne.dev/docs/components/timeline

> A vertical list of events, such as an activity feed, an order's shipping history or a ticket's audit trail. Each item has a dot, icon or avatar, a title, a time and optional content, joined by connector lines. Comes in default and compact densities, with tone-colored markers and an option to hide the connector.

```tsx title="timeline/demo.tsx"
import {
  GitMergeIcon,
  GitPullRequestIcon,
  MessageSquareIcon,
} from "lucide-react";
import {
  Timeline,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";

export default function TimelineDemo() {
  return (
    <Timeline className="w-full max-w-md">
      <TimelineItem>
        <TimelineIndicator>
          <GitPullRequestIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Maya Chen</strong> opened #482
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-02T09:14">Oct 2, 9:14</TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            Add retry with backoff to the webhook dispatcher.
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator>
          <MessageSquareIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Jonas Weber</strong> left a review
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-02T11:40">
              Oct 2, 11:40
            </TimelineTime>
          </TimelineHeader>
          <TimelineDescription>
            Looks good. Can we cap the delay at 30 seconds?
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
      <TimelineItem>
        <TimelineIndicator color="brand">
          <GitMergeIcon />
        </TimelineIndicator>
        <TimelineContent>
          <TimelineHeader>
            <TimelineTitle>
              <strong>Maya Chen</strong> merged into main
            </TimelineTitle>
            <TimelineTime dateTime="2026-10-03T08:05">Oct 3, 8:05</TimelineTime>
          </TimelineHeader>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/timeline
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import {
  Timeline,
  TimelineContent,
  TimelineDescription,
  TimelineHeader,
  TimelineIndicator,
  TimelineItem,
  TimelineTime,
  TimelineTitle,
} from "@/components/ui/timeline";
```

```tsx
<Timeline aria-label="Shipment history">
  <TimelineItem>
    <TimelineIndicator color="success" />
    <TimelineContent>
      <TimelineHeader>
        <TimelineTitle>Order delivered</TimelineTitle>
        <TimelineTime dateTime="2026-10-04T14:41">Today, 2:41 PM</TimelineTime>
      </TimelineHeader>
      <TimelineDescription>Left at the front door</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

The timeline is static markup with no `"use client"`, so it renders in server components.

### When to use

* Timeline: things that already happened, in order, where when they happened matters (activity, history, audit logs, tracking).
* [Stepper](/docs/components/stepper): steps the user still has to complete.
* [Item](/docs/components/item): a list of entities, not events.
* [Table](/docs/components/table): large logs that users filter, sort or export.

## Anatomy

```tsx
<Timeline>                     {/* <ol>, variant, connector */}
  <TimelineItem>               {/* <li> */}
    <TimelineIndicator />      {/* dot, icon tile or media + connector */}
    <TimelineContent>          {/* fills the rest of the row */}
      <TimelineHeader>         {/* title and time on one row */}
        <TimelineTitle />
        <TimelineTime />       {/* <time> */}
      </TimelineHeader>
      <TimelineDescription />  {/* body text or any content */}
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

| Part                  | Renders             | Notes                                                                                                                                                                                       |
| --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Timeline`            | `<ol>`              | Sets `--timeline-indicator` (marker size) and `--timeline-gap` (space between items) for the chosen `variant`.                                                                              |
| `TimelineItem`        | `<li>`              | A row: marker column plus content.                                                                                                                                                          |
| `TimelineIndicator`   | `<div aria-hidden>` | With no children, a dot. With children, a 28px round icon tile (`variant="icon"`) or a circle that an image or avatar fills (`variant="media"`). Draws the connector down to the next item. |
| `TimelineContent`     | `<div>`             | Aligns its first line with the marker and adds the gap below each item.                                                                                                                     |
| `TimelineHeader`      | `<div>`             | Flex row that wraps. The time is pushed to the end.                                                                                                                                         |
| `TimelineTitle`       | `<div>`             | Foreground text. `<strong>` inside is medium weight, for names.                                                                                                                             |
| `TimelineTime`        | `<time>`            | Muted, tabular. Pass `dateTime` with an ISO value.                                                                                                                                          |
| `TimelineDescription` | `<div>`             | Muted body text. Can hold badges, quotes or cards.                                                                                                                                          |

## Examples

### Dots

Leave `TimelineIndicator` empty for a dot. Without `color` it's a neutral ring; with `color` it's filled with a soft halo, useful for the latest or most important event.

Example `timeline/dots`: source in https://desyne.dev/docs/components/timeline.md

### Compact

`variant="compact"` shrinks markers to 20px and tightens spacing for dense activity feeds in sidebars and popovers.

Example `timeline/compact`: source in https://desyne.dev/docs/components/timeline.md

### Rich content

Content can be anything: a quoted reply, a badge, an attachment. Use `variant="media"` to fill the marker with an [`Avatar`](/docs/components/avatar) or image.

Example `timeline/rich-content`: source in https://desyne.dev/docs/components/timeline.md

### Without connector

`connector={false}` hides the lines (spacing stays the same), for feeds where items aren't a single continuous sequence.

Example `timeline/without-connector`: source in https://desyne.dev/docs/components/timeline.md

## Accessibility

* The timeline is an `<ol>`, so screen readers announce the number of events. Add an `aria-label` when the context doesn't already make clear what the list is.
* Markers are `aria-hidden`. If an icon or color carries meaning (e.g. failed vs. succeeded), say so in the title or description too.
* `TimelineTime` renders a `<time>` element; pass a machine-readable `dateTime` alongside friendly text like "2h ago".
* `TimelineTitle` is a `<div>`. If items are sections with their own headings, put a heading element inside it.

## Styling

### Data attributes

| Attribute                                                                        | On             | Values                           |
| -------------------------------------------------------------------------------- | -------------- | -------------------------------- |
| `data-slot="timeline"`                                                           | `Timeline`     | Always                           |
| `data-variant`                                                                   | `Timeline`     | `default` · `compact`            |
| `data-connector`                                                                 | `Timeline`     | `true` · `false`                 |
| `data-slot="timeline-item"`                                                      | `TimelineItem` | Always                           |
| `data-slot="timeline-indicator"`                                                 | Marker column  | Always                           |
| `data-slot="timeline-dot"`                                                       | Dot            | No children                      |
| `data-slot="timeline-connector"`                                                 | Line           | Always (hidden on the last item) |
| `data-slot="timeline-content"` / `-header` / `-title` / `-time` / `-description` | Parts          | Always                           |

### CSS variables

| Variable               | Default               | Compact               | Used for                     |
| ---------------------- | --------------------- | --------------------- | ---------------------------- |
| `--timeline-indicator` | `--spacing(7)` (28px) | `--spacing(5)` (20px) | Marker size and column width |
| `--timeline-gap`       | `--spacing(6)`        | `--spacing(3.5)`      | Space under each item        |

Override them on `Timeline`, e.g. `className="[--timeline-gap:--spacing(10)]"`.

## API Reference

### Timeline

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;compact&#x22;', default: '&#x22;default&#x22;', description: &#x22;Marker size and spacing.&#x22; },
  connector: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Draws lines between markers.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<ol>`.

### TimelineIndicator

<TypeTable
  type="{
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', description: &#x22;Fills the dot, or tints the icon tile. Omit for a neutral outline.&#x22; },
  variant: { type: '&#x22;icon&#x22; | &#x22;media&#x22;', default: '&#x22;icon&#x22;', description: &#x22;With children: a tinted or outlined icon tile, or a circle the child fills (images, avatars).&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Icon, image or avatar. Leave empty for a dot.&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes on the marker.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### TimelineTime

Accepts every prop of `<time>`, including `dateTime`.

### TimelineItem / TimelineContent / TimelineHeader / TimelineTitle / TimelineDescription

No extra props. `TimelineItem` accepts every prop of `<li>`; the others accept every prop of `<div>`.

## Related

* [Stepper](/docs/components/stepper): steps still to come.
* [Avatar](/docs/components/avatar): people in activity feeds.
* [Item](/docs/components/item): lists of entities.

---

# Description List

Source: https://desyne.dev/docs/components/description-list

> Term and value pairs for detail pages, settings summaries and record sidebars. A semantic dl with a side-by-side layout that stacks on small screens, or a stacked layout, plus optional dividers and two sizes. Works in server components.

```tsx title="description-list/demo.tsx"
import {
  DescriptionDetails,
  DescriptionList,
  DescriptionTerm,
} from "@/components/ui/description-list";

export default function DescriptionListDemo() {
  return (
    <DescriptionList divided className="w-full max-w-lg">
      <DescriptionTerm>Customer</DescriptionTerm>
      <DescriptionDetails>Harbor & Pine Studio</DescriptionDetails>
      <DescriptionTerm>Invoice</DescriptionTerm>
      <DescriptionDetails className="font-mono text-[0.8125rem]">
        INV-2041
      </DescriptionDetails>
      <DescriptionTerm>Issued</DescriptionTerm>
      <DescriptionDetails>October 1, 2026</DescriptionDetails>
      <DescriptionTerm>Due</DescriptionTerm>
      <DescriptionDetails>October 31, 2026 · Net 30</DescriptionDetails>
      <DescriptionTerm>Amount</DescriptionTerm>
      <DescriptionDetails className="font-medium tabular-nums">
        $4,280.00
      </DescriptionDetails>
    </DescriptionList>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/description-list
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import {
  DescriptionDetails,
  DescriptionList,
  DescriptionTerm,
} from "@/components/ui/description-list";
```

```tsx
<DescriptionList divided>
  <DescriptionTerm>Customer</DescriptionTerm>
  <DescriptionDetails>Harbor & Pine Studio</DescriptionDetails>
  <DescriptionTerm>Amount</DescriptionTerm>
  <DescriptionDetails>$4,280.00</DescriptionDetails>
</DescriptionList>
```

<Callout title="Terms and details are direct children">
  The layout is a CSS grid on the `<dl>` that styles its direct `<dt>` and
  `<dd>` children, so put them straight inside `DescriptionList`, one
  `DescriptionDetails` per term. Use a `Fragment` (not a `<div>`) when mapping
  over pairs.
</Callout>

### When to use

* Description List: read-only fields of one record, such as an invoice, a deployment or a user profile.
* [Table](/docs/components/table): many records that share the same fields.
* [Item](/docs/components/item): a list of entities with media and actions.
* [Card](/docs/components/card): a container for a description list with a title.

## Anatomy

```tsx
<DescriptionList>          {/* <dl>, layout, divided, size */}
  <DescriptionTerm />      {/* <dt> */}
  <DescriptionDetails />   {/* <dd> */}
</DescriptionList>
```

| Part                 | Renders | Notes                                                                                                                        |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `DescriptionList`    | `<dl>`  | Grid. `horizontal`: term column (`minmax(7rem, 33%)`) and details column from `sm` up, stacked below. `stacked`: one column. |
| `DescriptionTerm`    | `<dt>`  | Muted label.                                                                                                                 |
| `DescriptionDetails` | `<dd>`  | Foreground value. Long words wrap anywhere instead of overflowing.                                                           |

## Examples

### Stacked

`layout="stacked"` puts each term above its details, for narrow sidebars and multi-line values like addresses.

Example `description-list/stacked`: source in https://desyne.dev/docs/components/description-list.md

### With actions

Details are plain elements, so they can hold badges, links and buttons. Make `DescriptionDetails` a flex row to push an action to the end, and give each button a name that includes the field.

Example `description-list/actions`: source in https://desyne.dev/docs/components/description-list.md

### Sizes

`size="sm"` uses 13px text and tighter rows for cards and side panels; `md` is the default.

Example `description-list/sizes`: source in https://desyne.dev/docs/components/description-list.md

## Recipes

### Detail card

A deployment summary in a [`Card`](/docs/components/card), with a status badge, a commit hash and a copyable domain.

Example `description-list/recipe-detail-card`: source in https://desyne.dev/docs/components/description-list.md

## Accessibility

* Uses native `<dl>`, `<dt>` and `<dd>`, so screen readers announce terms and their values as pairs.
* Dividers are borders, not separate elements, so they add nothing to the reading order.
* When a value is only an icon or a color (e.g. a status dot), include text, as the [`Badge`](/docs/components/badge) does.
* Give actions in details names that include the field, e.g. `aria-label="Edit email"`, not just "Edit".

## Styling

### Data attributes

| Attribute                         | On                                           |
| --------------------------------- | -------------------------------------------- |
| `data-slot="description-list"`    | `DescriptionList`                            |
| `data-layout`                     | `DescriptionList` (`horizontal` · `stacked`) |
| `data-slot="description-term"`    | `DescriptionTerm`                            |
| `data-slot="description-details"` | `DescriptionDetails`                         |

### Term width

The horizontal layout reads `--dl-term-width` (default `33%`) for the term column:

```tsx
<DescriptionList className="[--dl-term-width:12rem]">…</DescriptionList>
```

### `descriptionListVariants`

The `tailwind-variants` function behind `DescriptionList`, for applying the layout to your own `<dl>`.

## API Reference

### DescriptionList

<TypeTable
  type="{
  layout: { type: '&#x22;horizontal&#x22; | &#x22;stacked&#x22;', default: '&#x22;horizontal&#x22;', description: &#x22;Side by side (stacks below sm), or term above details.&#x22; },
  divided: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Hairlines between pairs.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Text size and row spacing.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<dl>`.

### DescriptionTerm / DescriptionDetails

No extra props. Accept every prop of `<dt>` and `<dd>`.

## Related

* [Card](/docs/components/card): frame a description list with a title.
* [Table](/docs/components/table): many records with the same fields.
* [Badge](/docs/components/badge): statuses inside details.

---

# Empty

Source: https://desyne.dev/docs/components/empty

> An empty state for lists, tables, search results and new accounts. Media, a title, a short explanation and the next action, centered, in three surfaces and three sizes. Same composition style as Item and Card, and works in server components.

```tsx title="empty/demo.tsx"
"use client";

import { FolderOpenIcon, PlusIcon } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  Empty,
  EmptyActions,
  EmptyDescription,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty";

export default function EmptyDemo() {
  return (
    <Empty>
      <EmptyMedia variant="icon">
        <FolderOpenIcon />
      </EmptyMedia>
      <EmptyTitle>No projects yet</EmptyTitle>
      <EmptyDescription>
        Projects group your docs, tasks and files. Create one to get started, or
        import from Linear or Jira.
      </EmptyDescription>
      <EmptyActions>
        <Button>
          <PlusIcon />
          New project
        </Button>
        <Button variant="outline">Import</Button>
      </EmptyActions>
    </Empty>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/empty
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import {
  Empty,
  EmptyActions,
  EmptyDescription,
  EmptyMedia,
  EmptyTitle,
} from "@/components/ui/empty";
```

```tsx
<Empty>
  <EmptyMedia variant="icon">
    <FolderOpenIcon />
  </EmptyMedia>
  <EmptyTitle>No projects yet</EmptyTitle>
  <EmptyDescription>Create a project to get started.</EmptyDescription>
  <EmptyActions>
    <Button>New project</Button>
  </EmptyActions>
</Empty>
```

### When to use

* Empty: a place that would normally show content but has none, such as a new account, a cleared inbox or a search with no matches. Explain why, and offer the next step.
* [Alert](/docs/components/alert): a problem the user needs to know about, such as a failed load.
* [Skeleton](/docs/components/skeleton): content that's still loading. Don't show an empty state before the data arrives.

## Anatomy

```tsx
<Empty>                {/* variant, size */}
  <EmptyMedia />       {/* icon tile, round badge, avatars or illustration */}
  <EmptyTitle />       {/* what's empty */}
  <EmptyDescription /> {/* why, and what to do */}
  <EmptyActions />     {/* buttons or links */}
</Empty>
```

| Part               | Renders             | Notes                                                                                                                                               |
| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Empty`            | `<div>`             | Centered flex column, balanced text. `variant` sets the surface, `size` the padding and gap.                                                        |
| `EmptyMedia`       | `<div aria-hidden>` | `icon`: 40px bordered tile, like `ItemMedia`. `round`: 48px muted circle. `default`: no surface, for avatars or illustrations (bare SVGs get 32px). |
| `EmptyTitle`       | `<div>`             | 16px semibold. Put a heading element inside if the empty state stands in for a page section.                                                        |
| `EmptyDescription` | `<p>`               | Muted, max 24rem wide. Links inside are underlined.                                                                                                 |
| `EmptyActions`     | `<div>`             | Centered row that wraps.                                                                                                                            |

## Examples

### Outline

`variant="outline"` draws a dashed border, for empty page sections and places where content can be added or dropped. `EmptyMedia variant="round"` gives the icon a soft circle.

Example `empty/outline`: source in https://desyne.dev/docs/components/empty.md

### No search results

`variant="muted"` fills the background, for empty panels inside other surfaces. Add `role="status"` when the empty state appears in response to typing, so the change is announced. Offer a way out, like clearing the search.

Example `empty/search`: source in https://desyne.dev/docs/components/empty.md

### Avatars as media

`EmptyMedia` with the default variant holds anything, such as an [`AvatarGroup`](/docs/components/avatar). `size="lg"` adds room for full-page empty states.

Example `empty/avatars`: source in https://desyne.dev/docs/components/empty.md

### Inside a card

`size="sm"` with a smaller title and description fits card bodies and popovers.

Example `empty/in-card`: source in https://desyne.dev/docs/components/empty.md

## Accessibility

* `Empty` is a plain `<div>` with no role. Add `role="status"` when it replaces results in response to user input, so screen readers announce it.
* `EmptyMedia` is `aria-hidden`; make sure the title says what the icon shows.
* `EmptyTitle` is a `<div>`. When the empty state is the main content of a page or section, wrap the text in a heading at the right level: `<EmptyTitle><h2>No projects yet</h2></EmptyTitle>`.
* Name actions by what they do ("New project", "Clear search"), not "Click here".

## Styling

### Data slots

| Slot                            | Element            |
| ------------------------------- | ------------------ |
| `data-slot="empty"`             | `Empty`            |
| `data-slot="empty-media"`       | `EmptyMedia`       |
| `data-slot="empty-title"`       | `EmptyTitle`       |
| `data-slot="empty-description"` | `EmptyDescription` |
| `data-slot="empty-actions"`     | `EmptyActions`     |

### `emptyVariants`

The `tailwind-variants` function behind `Empty`, for applying the same layout to your own element (for example a `<section>` or a table cell).

## API Reference

### Empty

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;outline&#x22; | &#x22;muted&#x22;', default: '&#x22;default&#x22;', description: &#x22;Surface: none, dashed border, or muted fill.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Padding (24, 32 or 48px) and gap.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### EmptyMedia

<TypeTable
  type="{
  variant: { type: '&#x22;default&#x22; | &#x22;icon&#x22; | &#x22;round&#x22;', default: '&#x22;default&#x22;', description: &#x22;icon: 40px bordered tile. round: 48px muted circle. default: no surface.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### EmptyTitle / EmptyActions

No extra props. Accept every prop of `<div>`.

### EmptyDescription

No extra props. Accepts every prop of `<p>`.

## Related

* [Item](/docs/components/item): the rows that fill the list once it isn't empty.
* [Card](/docs/components/card): a frame for small empty states.
* [Skeleton](/docs/components/skeleton): placeholders while loading.

---

# Scroll Area

Source: https://desyne.dev/docs/components/scroll-area

> A scroll container with thin, themed scrollbars and optional fading edges. Native scrolling (wheel, touch, keyboard and scroll snapping all work as usual), styled with CSS only, vertically, horizontally or both, with always-visible, hover-only or hidden scrollbars.

```tsx title="scroll-area/demo.tsx"
import { ScrollArea } from "@/components/ui/scroll-area";

const releases = [
  ["4.12.0", "Oct 2", "Bulk edit for invoices and a new CSV importer."],
  ["4.11.3", "Sep 26", "Fixed rounding in multi-currency totals."],
  ["4.11.2", "Sep 22", "Faster search on workspaces with 10k+ documents."],
  ["4.11.0", "Sep 15", "Approval rules for expenses over a set amount."],
  ["4.10.4", "Sep 8", "Webhook retries now back off exponentially."],
  ["4.10.0", "Sep 1", "Dark mode for the mobile apps."],
  ["4.9.2", "Aug 25", "Audit log export to S3 and GCS."],
  ["4.9.0", "Aug 18", "Custom fields on vendors and customers."],
  ["4.8.1", "Aug 11", "SAML just-in-time provisioning."],
  ["4.8.0", "Aug 4", "Recurring invoices with proration."],
];

export default function ScrollAreaDemo() {
  return (
    <div className="w-full max-w-sm rounded-xl border bg-card">
      <h3 className="border-b px-4 py-3 font-medium text-sm">Changelog</h3>
      <ScrollArea className="h-64" aria-label="Changelog">
        <ul className="divide-y">
          {releases.map(([version, date, note]) => (
            <li key={version} className="px-4 py-3">
              <div className="flex items-baseline justify-between gap-2">
                <span className="font-medium font-mono text-xs">
                  v{version}
                </span>
                <span className="text-muted-foreground text-xs">{date}</span>
              </div>
              <p className="mt-1 text-muted-foreground text-sm">{note}</p>
            </li>
          ))}
        </ul>
      </ScrollArea>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/scroll-area
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import { ScrollArea } from "@/components/ui/scroll-area";
```

```tsx
<ScrollArea className="h-64" aria-label="Changelog">
  {/* long content */}
</ScrollArea>
```

Give the scroll area a fixed height (or width for horizontal scrolling), or put it in a flex or grid parent that limits its size.

### When to use

* Scroll Area: a region inside a page that scrolls on its own, such as a list in a card, a row of cards, or a wide table, where the default scrollbar looks heavy.
* Let the page scroll when the content is the main thing on the page. Nested scrolling regions are harder to use, especially on touch devices.
* [Carousel](/docs/components/carousel): horizontally scrolling slides with previous and next buttons.

## Anatomy

```tsx
<ScrollArea>   {/* the scroll container, tabIndex=0 */}
  {children}
</ScrollArea>
```

| Part         | Renders | Notes                                                                                                                                                                                                                     |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ScrollArea` | `<div>` | `overflow: auto` on the chosen axes, a thin scrollbar via `scrollbar-width` and `scrollbar-color` (with `::-webkit-scrollbar` styles for older WebKit), and `overscroll-behavior: contain`. Focusable, with a focus ring. |

There's no custom scrollbar element: the browser draws the scrollbar, so platform behaviors like overlay scrollbars on macOS and momentum scrolling are kept.

## Examples

### Horizontal

`orientation="horizontal"` scrolls sideways. Give the content `w-max` (or a fixed width) so it doesn't wrap.

Example `scroll-area/horizontal`: source in https://desyne.dev/docs/components/scroll-area.md

### Fade edges

`fade` masks the edges that have more content beyond them, and updates as you scroll and when the content resizes. Pass a number for the fade size in px (default 24). The mask covers everything on the element, borders included, so put borders and backgrounds on a wrapper.

Example `scroll-area/fade`: source in https://desyne.dev/docs/components/scroll-area.md

### Both directions

`orientation="both"` scrolls on both axes. Sticky headers and columns work as usual, since the scroll area is the scroll container.

Example `scroll-area/both`: source in https://desyne.dev/docs/components/scroll-area.md

### Scrollbar visibility

`scrollbar="thin"` (default) is always visible, `hover` shows it only while the pointer is over the area or it has keyboard focus, and `hidden` removes it while keeping wheel, touch and keyboard scrolling.

Example `scroll-area/scrollbar`: source in https://desyne.dev/docs/components/scroll-area.md

## Accessibility

* The scroll area has `tabIndex={0}` by default, so keyboard users can focus it and scroll with the arrow keys, Page Up/Down, Home and End. Pass `tabIndex={-1}` if the content is already fully reachable by tabbing through focusable children.
* Because it's focusable, give it a name with `aria-label` or `aria-labelledby`, and consider `role="region"` for large, landmark-like areas.
* With `scrollbar="hidden"`, nothing shows that the area scrolls. Use it only when the content makes it obvious (a cut-off row of chips, a fade edge).
* Fades are visual only and respect the content beneath them; they don't block pointer events.

## Styling

### Data attributes

| Attribute                 | On   | Values                             |
| ------------------------- | ---- | ---------------------------------- |
| `data-slot="scroll-area"` | Root | Always                             |
| `data-orientation`        | Root | `vertical` · `horizontal` · `both` |

### Scrollbar color

The thumb color is the `--scroll-thumb` variable (35% of `--muted-foreground`). Override it on the scroll area or any ancestor:

```tsx
<ScrollArea className="[--scroll-thumb:var(--brand)]">…</ScrollArea>
```

### `scrollAreaVariants`

The `tailwind-variants` function behind `ScrollArea`. Apply it to any element to get the same scrollbars without the fade logic, for example a `<pre>` or a `<table>` wrapper.

## API Reference

<TypeTable
  type="{
  orientation: { type: '&#x22;vertical&#x22; | &#x22;horizontal&#x22; | &#x22;both&#x22;', default: '&#x22;vertical&#x22;', description: &#x22;Which axes scroll.&#x22; },
  scrollbar: { type: '&#x22;thin&#x22; | &#x22;hover&#x22; | &#x22;hidden&#x22;', default: '&#x22;thin&#x22;', description: &#x22;Scrollbar visibility.&#x22; },
  fade: { type: &#x22;boolean | number&#x22;, default: &#x22;false&#x22;, description: &#x22;Fades edges with more content beyond them. A number sets the size in px (true = 24).&#x22; },
  tabIndex: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Makes the area keyboard-focusable.&#x22; },
  className: { type: &#x22;string&#x22; },
}"
/>

Also accepts every prop of `<div>`, including `ref` and `onScroll`.

## Related

* [Carousel](/docs/components/carousel): slides with navigation.
* [Table](/docs/components/table): wide tables inside a scroll area.
* [Card](/docs/components/card): a frame around a scrolling list.

---

# Alert

Source: https://desyne.dev/docs/components/alert

> An inline callout for messages that belong to the page — status, warnings, errors and announcements. Four styles, seven colors, default or custom icons, trailing actions and an optional dismiss button.

```tsx title="alert/demo.tsx"
"use client";

import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";

export default function AlertDemo() {
  return (
    <Alert showIcon className="max-w-md">
      <AlertTitle>A new version is available</AlertTitle>
      <AlertDescription>
        Refresh the page to get the latest features and fixes.
      </AlertDescription>
    </Alert>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/alert
```

npm dependencies (installed by the CLI): lucide-react, react-aria-components, tailwind-variants.

## Usage

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

```tsx
<Alert color="warning" showIcon>
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>Your trial ends in 3 days.</AlertDescription>
</Alert>
```

<Callout title="Alerts are live regions">
  The default role follows the color. `danger` and `warning` alerts render
  with `role="alert"` (assertive — announced immediately, interrupting the
  user); every other color renders with `role="status"` (polite — announced
  when the user is idle). For static notices that are on the page from the
  start, pass `role="note"` so they aren't announced at all.
</Callout>

### When to use

* Alert — a message tied to a page or section that stays until the situation changes: a failed deploy, a form error, a plan limit, a maintenance notice.
* [Toast](/docs/components/toast) — brief, non-blocking feedback after an action ("Saved", "Invite sent") that disappears on its own.
* [Dialog](/docs/components/dialog) with `role="alertdialog"` — when the user must make a decision before continuing.
* [Badge](/docs/components/badge) — a compact status label on an item, not a message.

## Anatomy

```tsx
<Alert icon={<Icon />} action={<Button />} onDismiss={…}>
  {/* leading icon: `icon`, or the tone's default with `showIcon` */}
  <AlertTitle />         {/* short summary */}
  <AlertDescription />   {/* details, lists, links */}
  {/* trailing `action` slot, then the dismiss button */}
</Alert>
```

| Part               | Renders                                       | Notes                                                                                                               |
| ------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `Alert`            | `<div role="alert">` or `<div role="status">` | Root flex row. `alert` for `danger`/`warning`, `status` otherwise. Sets the tone variables and `data-slot="alert"`. |
| Icon               | `<svg>`                                       | From `icon`, or the tone's default when `showIcon` is set. Sized to 16px and tinted with the tone.                  |
| Content            | `<div>`                                       | Column that wraps `children` (title, description and anything else).                                                |
| `AlertTitle`       | `<div>`                                       | Medium-weight summary line.                                                                                         |
| `AlertDescription` | `<div>`                                       | Muted supporting text. Can hold paragraphs, lists and links.                                                        |
| Action             | `<div>`                                       | Rendered when `action` is set. Vertically centered on the trailing side.                                            |
| Dismiss            | `<button>`                                    | React Aria `Button` with `aria-label="Dismiss"`, rendered when `onDismiss` is set.                                  |

## Examples

### Variants

`soft` (default) tints the whole surface. `outline` is a plain card with a colored icon, `accent` adds a colored leading bar for dense layouts, and `solid` fills with the tone for banners that must not be missed.

Example `alert/variants`: source in https://desyne.dev/docs/components/alert.md

### Colors

Match the color to the message: `info` (default) for neutral information, `success` for completed actions, `warning` for something that needs attention soon, `danger` for errors and failures, and `neutral` for low-emphasis notes. `primary` and `brand` are also available for product announcements.

Example `alert/colors`: source in https://desyne.dev/docs/components/alert.md

### Title and description

Both parts are optional. Use a title alone for one-line confirmations, a description alone for explanatory notes, and both when the summary needs context.

Example `alert/content`: source in https://desyne.dev/docs/components/alert.md

### Custom icon

`showIcon` adds the tone's default icon (info, check, triangle or circle; `neutral` has none). Pass `icon` to use any other icon; it gets the same size and tint.

Example `alert/custom-icon`: source in https://desyne.dev/docs/components/alert.md

### Rich content

`AlertDescription` accepts any content. Lists work well for validation summaries, and a [`Link`](/docs/components/link) can point to more detail.

Example `alert/rich-content`: source in https://desyne.dev/docs/components/alert.md

### Actions

`action` renders buttons on the trailing side, vertically centered. Keep it to one or two small buttons, and make sure the action is reachable elsewhere if the alert can be dismissed.

Example `alert/actions`: source in https://desyne.dev/docs/components/alert.md

### Dismissible

`onDismiss` adds a close button. The alert doesn't hide itself — remove it from your state in the callback, and persist the choice if it shouldn't come back on reload.

Example `alert/dismissible`: source in https://desyne.dev/docs/components/alert.md

### Showing results of an action

Render the alert conditionally after an async action. A `danger` alert has `role="alert"`, so screen readers announce it as soon as it appears, without moving focus. A `success` or `info` result gets `role="status"` and is announced politely instead.

Example `alert/live`: source in https://desyne.dev/docs/components/alert.md

### shadcn compatibility

The shadcn variant names still work: `default` maps to `outline` + `neutral`, and `destructive` maps to `outline` + `danger`. An explicit `color` wins over the alias.

Example `alert/shadcn`: source in https://desyne.dev/docs/components/alert.md

## Recipes

### Billing banner

A full-bleed `solid` alert at the top of the app shell, with an action and a dismiss button. `rounded-none` makes it sit flush with the frame.

Example `alert/recipe-billing-banner`: source in https://desyne.dev/docs/components/alert.md

### Server error in a form

Field errors belong next to their fields; errors that come back from the server go in an alert above the form. Clear it when the user resubmits.

Example `alert/recipe-form-error`: source in https://desyne.dev/docs/components/alert.md

### Plan limit

An `accent` warning with a [`Meter`](/docs/components/meter) inside the content column and an upgrade action.

Example `alert/recipe-plan-limit`: source in https://desyne.dev/docs/components/alert.md

## Accessibility

* The root is a live region whose urgency follows `color`: `danger` and `warning` get `role="alert"` (assertive — announced immediately when inserted or changed); every other color gets `role="status"` (polite — announced when the user is idle). Legacy `variant="destructive"` resolves to `danger`, so it stays assertive.
* An explicit `role` always wins. Use `role="note"` for static content that's on the page from the start and shouldn't be announced, or `role="alert"` to make a non-danger tone urgent.
* Live regions announce content that changes after they're in the DOM. For an alert that appears in response to an action, render it conditionally (as above) rather than toggling its text inside an always-present element.
* Alerts never move focus. If the user must act, put the action in the alert and consider a [Dialog](/docs/components/dialog) instead.
* Icons are decorative. The title (or description) must carry the meaning on its own; don't rely on color alone.
* The dismiss button is a React Aria `Button` labelled "Dismiss", with a keyboard-only focus ring.
* Avoid auto-dismissing alerts; users of assistive tech may not have finished reading them.

### Keyboard

| Key                                 | Action                                                   |
| ----------------------------------- | -------------------------------------------------------- |
| <kbd>Tab</kbd>                      | Moves focus to the action buttons and the dismiss button |
| <kbd>Space</kbd> / <kbd>Enter</kbd> | Activates the focused button                             |

## Styling

### Data slots

| Slot                            | Element                                                         |
| ------------------------------- | --------------------------------------------------------------- |
| `data-slot="alert"`             | Root                                                            |
| `data-slot="alert-title"`       | `AlertTitle`                                                    |
| `data-slot="alert-description"` | `AlertDescription` (text becomes `--tone-fg` at 85% on `solid`) |

### Tone variables

The `color` prop sets `--tone` and `--tone-fg` on the root; every variant styles itself from those. Set them yourself for a one-off color:

```tsx
<Alert
  variant="accent"
  icon={<SparklesIcon />}
  className="[--tone:var(--color-violet-600)] [--tone-fg:white]"
>
  <AlertTitle>New in 2.4</AlertTitle>
</Alert>
```

| Variable    | Used for                                                                           |
| ----------- | ---------------------------------------------------------------------------------- |
| `--tone`    | Icon color, border and tint (`soft`), leading bar (`accent`), background (`solid`) |
| `--tone-fg` | Text and icon on `solid`                                                           |

### `alertVariants`

The `tailwind-variants` function behind the root. Use it to style your own element as an alert.

```tsx
import { alertVariants } from "@/components/ui/alert";

<section className={alertVariants({ variant: "accent", color: "success" })}>…</section>;
```

## API Reference

### Alert

<TypeTable
  type="{
  variant: {
    type: '&#x22;soft&#x22; | &#x22;outline&#x22; | &#x22;accent&#x22; | &#x22;solid&#x22; | &#x22;default&#x22; | &#x22;destructive&#x22;',
    default: '&#x22;soft&#x22;',
    description: 'Visual style. &#x22;default&#x22; and &#x22;destructive&#x22; are shadcn aliases that render as &#x22;outline&#x22;.',
  },
  color: {
    type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;',
    default: '&#x22;info&#x22;',
    description: 'Color tone. Defaults to &#x22;neutral&#x22; for variant=&#x22;default&#x22; and &#x22;danger&#x22; for variant=&#x22;destructive&#x22;.',
  },
  showIcon: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shows the tone's default icon. The neutral tone has no default icon.&#x22; },
  icon: { type: &#x22;ReactNode&#x22;, description: &#x22;Custom leading icon. Takes precedence over showIcon.&#x22; },
  action: { type: &#x22;ReactNode&#x22;, description: &#x22;Buttons or links rendered on the trailing side.&#x22; },
  onDismiss: { type: &#x22;() => void&#x22;, description: &#x22;Renders a dismiss button and is called when it's pressed.&#x22; },
  role: { type: &#x22;AriaRole&#x22;, default: '&#x22;alert&#x22; for danger/warning, &#x22;status&#x22; otherwise', description: 'Live-region role. Pass &#x22;note&#x22; for static content that should not be announced; an explicit value always wins.' },
  className: { type: &#x22;string&#x22;, description: &#x22;Classes merged into alertVariants.&#x22; },
  children: { type: &#x22;ReactNode&#x22;, description: &#x22;Content, usually AlertTitle and AlertDescription.&#x22; },
}"
/>

Also accepts every prop of `<div>`.

### AlertTitle / AlertDescription

Accept every prop of `<div>`.

### alertVariants

<TypeTable
  type="{
  variant: { type: '&#x22;soft&#x22; | &#x22;outline&#x22; | &#x22;accent&#x22; | &#x22;solid&#x22;', default: '&#x22;soft&#x22;' },
  color: { type: &#x22;Tone&#x22;, default: '&#x22;info&#x22;' },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

## Related

* [Toast](/docs/components/toast) — temporary, non-blocking feedback.
* [Dialog](/docs/components/dialog) — for messages that need a decision.
* [Badge](/docs/components/badge) — compact status labels.
* [Meter](/docs/components/meter) — show the level behind a quota warning.

---

# Progress Bar

Source: https://desyne.dev/docs/components/progress-bar

> Shows the progress of an operation over time, as a bar or a circle. Determinate or indeterminate, with a visible label, locale-aware value formatting, custom value text, three sizes and seven colors.

```tsx title="progress-bar/demo.tsx"
"use client";

import { useEffect, useState } from "react";
import { ProgressBar } from "@/components/ui/progress-bar";

export default function ProgressBarDemo() {
  const [value, setValue] = useState(18);
  useEffect(() => {
    const timer = setTimeout(() => setValue(68), 600);
    return () => clearTimeout(timer);
  }, []);
  return (
    <ProgressBar className="max-w-xs" label="Uploading files" value={value} />
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/progress-bar
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { ProgressBar, ProgressCircle } from "@/components/ui/progress-bar";
```

```tsx
<ProgressBar label="Uploading files" value={40} />
<ProgressCircle aria-label="Syncing" value={60} />
```

<Callout title="Animation keyframes">
  The indeterminate bar uses the `animate-indeterminate` keyframes from the
  theme CSS, which the registry adds on install. The circle's indeterminate
  state uses Tailwind's built-in `animate-spin`.
</Callout>

### When to use

* Progress Bar — a task that is running and will finish: uploads, imports, exports, multi-step setup. Use `isIndeterminate` while the duration is unknown.
* [Meter](/docs/components/meter) — a level within a known range that isn't "progressing": storage used, quota, password strength.
* [Spinner](/docs/components/spinner) — a short, unmeasured wait in a small space, such as inside a button or badge.
* [Skeleton](/docs/components/skeleton) — while the layout of content that is about to appear is known.

## Anatomy

```tsx
<ProgressBar label="…">   {/* role="progressbar" */}
  {/* header: Label + value text */}
  {/* track */}
  {/*   fill (width = percentage) */}
</ProgressBar>

<ProgressCircle>           {/* role="progressbar" */}
  {/* svg: track circle + fill circle */}
  {/* centered value text (md and lg) */}
</ProgressCircle>
```

| Part             | Renders                    | Notes                                                                                                  |
| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `ProgressBar`    | `<div role="progressbar">` | React Aria `ProgressBar`. Sets `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`. |
| Label            | `Label` (`<span>`)         | Rendered when `label` is set and wired up as the accessible name.                                      |
| Value text       | `<span>`                   | The formatted value (or `valueLabel`). Hidden when `showValue={false}` or indeterminate.               |
| Track            | `<div>`                    | Full-width, rounded, tinted with the tone at 15%.                                                      |
| Fill             | `<div>`                    | Width follows the percentage with a 500ms transition; slides back and forth when indeterminate.        |
| `ProgressCircle` | `<div role="progressbar">` | Same semantics; renders an `aria-hidden` SVG ring and an optional centered value.                      |

## Examples

### Sizes

`md` (8px) is the default. Use `sm` (4px) inside cards, lists and dialogs, and `lg` (12px) when the bar is the main content of the view.

Example `progress-bar/sizes`: source in https://desyne.dev/docs/components/progress-bar.md

### Colors

`brand` is the default. Switch to `success` when a task completes, and to `warning` or `danger` when it stalls or fails, so the state is visible at a glance.

Example `progress-bar/colors`: source in https://desyne.dev/docs/components/progress-bar.md

### Indeterminate

Set `isIndeterminate` when you can't measure progress yet, such as while connecting or analyzing. The value text is hidden and `aria-valuenow` is removed, so screen readers announce it as busy rather than 0%.

Example `progress-bar/indeterminate`: source in https://desyne.dev/docs/components/progress-bar.md

### Custom value text

`valueLabel` replaces the percentage with your own text, like "3 of 12 files". It's also used as `aria-valuetext`, so pass a string. Combine it with `maxValue` to work in your own units.

Example `progress-bar/value-label`: source in https://desyne.dev/docs/components/progress-bar.md

### Formatting and ranges

`minValue` and `maxValue` (0 and 100 by default) set the range. `formatOptions` takes any `Intl.NumberFormatOptions`: the default `percent` style formats the percentage, every other style formats the raw value in the user's locale.

Example `progress-bar/format`: source in https://desyne.dev/docs/components/progress-bar.md

### Without a visible label

When the label lives elsewhere in your layout, point to it with `aria-labelledby` (or pass `aria-label`) and hide the built-in value with `showValue={false}`.

Example `progress-bar/no-label`: source in https://desyne.dev/docs/components/progress-bar.md

### Live updates

Update `value` as work progresses; the fill animates between values. Change `label` and `color` to reflect the final state.

Example `progress-bar/live`: source in https://desyne.dev/docs/components/progress-bar.md

### Progress circle

`ProgressCircle` shows the same information in a compact ring: `sm` (20px) for inline status, `md` (48px) and `lg` (80px) for dashboards and cards. It has no built-in label, so `aria-label` or `aria-labelledby` is required. The percentage appears in the center at `md` and `lg`. It has its own page, [Progress Circle](/docs/components/progress-circle), with more sizes and custom center content.

Example `progress-bar/circle`: source in https://desyne.dev/docs/components/progress-bar.md

### Indeterminate circle

With `isIndeterminate`, the ring becomes a spinning quarter arc.

Example `progress-bar/circle-indeterminate`: source in https://desyne.dev/docs/components/progress-bar.md

### Circle with value text

`valueLabel` works for circles too; keep it short enough to fit the ring. Pair small circles with a nearby text label.

Example `progress-bar/circle-value-label`: source in https://desyne.dev/docs/components/progress-bar.md

## Recipes

### Upload list

Per-file progress in a list. Each bar has its own `aria-label`, turns `danger` on failure, and is replaced by a check icon once the upload finishes.

Example `progress-bar/recipe-upload-list`: source in https://desyne.dev/docs/components/progress-bar.md

### Data import

Start indeterminate while the file is analyzed, then switch to a determinate bar that counts rows with `valueLabel`.

Example `progress-bar/recipe-import`: source in https://desyne.dev/docs/components/progress-bar.md

### Onboarding checklist

A large `ProgressCircle` driven by the number of completed steps, using `maxValue` so the ring maps directly to the checklist.

Example `progress-bar/recipe-onboarding`: source in https://desyne.dev/docs/components/progress-bar.md

## Accessibility

* Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and a formatted `aria-valuetext` (your `valueLabel`, or the value formatted with `formatOptions`).
* Indeterminate bars omit `aria-valuenow` and `aria-valuetext`, so they're announced as busy.
* Every progress bar needs an accessible name: `label`, `aria-label` or `aria-labelledby`. `ProgressCircle` has no `label` prop, so always pass one of the aria props.
* Progress bars are not live regions; screen readers read the value when the user reaches it. Announce completion separately (for example with a [toast](/docs/components/toast)) if it matters.
* Respects `prefers-reduced-motion`. The fill jumps to each new value instead of animating. The indeterminate bar stops sliding and becomes a full-width bar that fades gently in and out, so it never looks like a partial value, and the indeterminate circle stops spinning and fades the same way. Screen readers get the same `aria-valuenow` / `aria-valuetext` (or no value when indeterminate) in both modes.

## Styling

### Data slots

| Slot                          | Element               |
| ----------------------------- | --------------------- |
| `data-slot="progress-bar"`    | `ProgressBar` root    |
| `data-slot="progress-circle"` | `ProgressCircle` root |
| `data-slot="label"`           | The visible label     |

### Render props

`className` accepts a function of the render state, which exposes `percentage`, `valueText` and `isIndeterminate`:

```tsx
<ProgressBar
  label="Upload"
  value={value}
  className={({ percentage }) => (percentage === 100 ? "opacity-60" : "")}
/>
```

Indeterminate bars have no `aria-valuenow`, so you can also target them with `[&:not([aria-valuenow])]:…`.

### Tone variables

`color` sets `--tone` on the root. The track uses `--tone` at 15% and the fill uses it at full strength, so a custom color only needs one variable:

```tsx
<ProgressBar label="Rendering" value={40} className="[--tone:var(--color-violet-600)]" />
```

## API Reference

### ProgressBar

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label, used as the accessible name.&#x22; },
  value: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Current value, clamped to the range.&#x22; },
  minValue: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Start of the range.&#x22; },
  maxValue: { type: &#x22;number&#x22;, default: &#x22;100&#x22;, description: &#x22;End of the range.&#x22; },
  isIndeterminate: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Shows an animated bar and hides the value when progress can't be measured.&#x22; },
  showValue: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the value text next to the label.&#x22; },
  valueLabel: { type: &#x22;ReactNode&#x22;, description: 'Replaces the formatted value, e.g. &#x22;3 of 12 files&#x22;. Also used as aria-valuetext, so prefer a string.' },
  formatOptions: { type: &#x22;Intl.NumberFormatOptions&#x22;, default: &#x22;{ style: 'percent' }&#x22;, description: &#x22;How the value is formatted.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', default: '&#x22;brand&#x22;', description: &#x22;Color tone of the track and fill.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Track height: 4px, 8px or 12px.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there is no visible label.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of an element that labels the bar.&#x22; },
  className: { type: &#x22;string | ((state: ProgressBarRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ProgressBar`](https://react-aria.adobe.com/ProgressBar#api), such as `id`, `style` and `aria-describedby`. The children are rendered by the component and can't be replaced.

### ProgressCircle

<TypeTable
  type="{
  value: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Current value, clamped to the range.&#x22; },
  minValue: { type: &#x22;number&#x22;, default: &#x22;0&#x22; },
  maxValue: { type: &#x22;number&#x22;, default: &#x22;100&#x22; },
  isIndeterminate: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Spins a quarter arc and hides the value.&#x22; },
  showValue: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the value in the center. Ignored at size sm.&#x22; },
  valueLabel: { type: &#x22;ReactNode&#x22;, description: &#x22;Replaces the formatted value in the center and in aria-valuetext.&#x22; },
  formatOptions: { type: &#x22;Intl.NumberFormatOptions&#x22;, default: &#x22;{ style: 'percent' }&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', default: '&#x22;brand&#x22;' },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;md&#x22;', description: &#x22;Diameter: 20px, 48px or 80px.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name. Required unless aria-labelledby is set.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22; },
  className: { type: &#x22;string | ((state: ProgressBarRenderProps) => string)&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ProgressBar`](https://react-aria.adobe.com/ProgressBar#api).

## Related

* [Meter](/docs/components/meter) — a level within a range, like storage used.
* [Spinner](/docs/components/spinner) — a compact indeterminate indicator.
* [Skeleton](/docs/components/skeleton) — placeholders while content loads.
* [Toast](/docs/components/toast) — announce when a long task finishes.

---

# Meter

Source: https://desyne.dev/docs/components/meter

> Shows a measurement within a known range, like storage used, a quota or password strength. The color follows configurable thresholds from success to warning to danger, with a segmented style, custom value text and locale-aware formatting.

```tsx title="meter/demo.tsx"
"use client";

import { Meter } from "@/components/ui/meter";

export default function MeterDemo() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-5">
      <Meter label="Storage" value={42} />
      <Meter label="Memory" value={81} />
      <Meter label="CPU" value={95} />
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/meter
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { Meter } from "@/components/ui/meter";
```

```tsx
<Meter label="Storage" value={72} />
```

Without a `color`, the bar is `success` below 75%, `warning` from 75% and `danger` from 90%. Change the cut-offs with `thresholds`, or set `color` to use one fixed tone.

### When to use

* Meter — a level within a known range that can go up or down: disk usage, seats, budget spent, signal or password strength.
* [Progress Bar](/docs/components/progress-bar) — the completion of a task that is running and will finish.
* [Spinner](/docs/components/spinner) and [Skeleton](/docs/components/skeleton) — waiting for something to load, where there's no value to show.

## Anatomy

```tsx
<Meter label="…">          {/* role="meter progressbar" */}
  {/* header: Label + value text */}
  {/* track + fill, or a row of segments */}
</Meter>
```

| Part         | Renders                          | Notes                                                                                                     |
| ------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `Meter`      | `<div role="meter progressbar">` | React Aria `Meter`. Sets `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`.          |
| Label        | `Label` (`<span>`)               | Rendered when `label` is set and used as the accessible name.                                             |
| Value text   | `<span>`                         | The formatted value, or `valueLabel`. Hidden with `showValue={false}`.                                    |
| Track + fill | `<div>` › `<div>`                | Muted track with a fill whose width follows the percentage (500ms transition).                            |
| Segments     | `<div>` × `segments`             | Replaces the track when `segments` is set. A segment fills once the value reaches its share of the range. |

## Examples

### Thresholds

`thresholds` takes two percentages: where the bar turns `warning` and where it turns `danger`. They're measured against the percentage of the range, not the raw value.

Example `meter/thresholds`: source in https://desyne.dev/docs/components/meter.md

### Fixed color

Set `color` when the value isn't "good" or "bad", such as a score or a completeness level. `color` always wins over `thresholds`.

Example `meter/colors`: source in https://desyne.dev/docs/components/meter.md

### When low is bad

Thresholds assume higher is worse. For values like battery or health scores, compute the color yourself and pass it in.

Example `meter/low-is-bad`: source in https://desyne.dev/docs/components/meter.md

### Sizes

`md` (8px) is the default; `sm` (6px) suits cards, tables and dense dashboards.

Example `meter/sizes`: source in https://desyne.dev/docs/components/meter.md

### Segments

`segments` splits the bar into equal pieces, for battery, signal or rating-style displays. Segments fill in whole steps, so pick a count that divides your range cleanly.

Example `meter/segments`: source in https://desyne.dev/docs/components/meter.md

### Custom value text

`valueLabel` replaces the percentage with your own text. It's also used as `aria-valuetext`, so pass a string that reads well on its own.

Example `meter/value-label`: source in https://desyne.dev/docs/components/meter.md

### Formatting and ranges

Set `minValue` and `maxValue` to work in real units, and `formatOptions` to format the value in the user's locale. With the default `percent` style the percentage is shown; any other style formats the raw value.

Example `meter/format`: source in https://desyne.dev/docs/components/meter.md

### Without a visible label

In tables and lists, pass `aria-label` and hide the value with `showValue={false}` if you show it elsewhere.

Example `meter/no-label`: source in https://desyne.dev/docs/components/meter.md

## Recipes

### Usage quotas

Plan limits in a billing card. Each meter uses `maxValue` and a `valueLabel` in real units, and turns amber and red as it approaches the limit.

Example `meter/recipe-usage-quotas`: source in https://desyne.dev/docs/components/meter.md

### Password strength

A segmented meter under a [`TextField`](/docs/components/text-field), with a color and label computed from a simple score.

Example `meter/recipe-password-strength`: source in https://desyne.dev/docs/components/meter.md

### Server health

Compact meters in cards, with a [`Badge`](/docs/components/badge) summarizing the worst reading.

Example `meter/recipe-server-health`: source in https://desyne.dev/docs/components/meter.md

## Accessibility

* Renders `role="meter progressbar"`: browsers that support the `meter` role use it, others fall back to `progressbar`.
* `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext` are set for you. `aria-valuetext` is your `valueLabel`, or the value formatted with `formatOptions`.
* Every meter needs an accessible name: `label`, `aria-label` or `aria-labelledby`.
* Color reinforces the value but never replaces it; keep the value text visible or describe the state in `valueLabel` ("Fair", "Critical").
* Meters aren't live regions. Changes aren't announced until the user reaches the meter.

## Styling

### Data slots

| Slot                | Element           |
| ------------------- | ----------------- |
| `data-slot="meter"` | Root              |
| `data-slot="label"` | The visible label |

### Render props

`className` accepts a function of the render state (`percentage`, `valueText`):

```tsx
<Meter
  label="Disk"
  value={value}
  className={({ percentage }) => (percentage >= 90 ? "font-medium" : "")}
/>
```

### Tone variables

The resolved tone sets `--tone` on the track (or the segment row), and the fill uses `bg-(--tone)`. The track itself is `bg-muted`.

## API Reference

### Meter

<TypeTable
  type="{
  label: { type: &#x22;ReactNode&#x22;, description: &#x22;Visible label, used as the accessible name.&#x22; },
  value: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Current value, clamped to the range.&#x22; },
  minValue: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Start of the range.&#x22; },
  maxValue: { type: &#x22;number&#x22;, default: &#x22;100&#x22;, description: &#x22;End of the range.&#x22; },
  showValue: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the value text next to the label.&#x22; },
  valueLabel: { type: &#x22;ReactNode&#x22;, description: 'Replaces the formatted value, e.g. &#x22;7.2 of 10 GB&#x22;. Also used as aria-valuetext, so prefer a string.' },
  formatOptions: { type: &#x22;Intl.NumberFormatOptions&#x22;, default: &#x22;{ style: 'percent' }&#x22;, description: &#x22;How the value is formatted.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', description: &#x22;Fixed tone. When omitted, the tone follows thresholds.&#x22; },
  thresholds: { type: &#x22;[number, number]&#x22;, default: &#x22;[75, 90]&#x22;, description: &#x22;Percentages where the bar turns warning and danger.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22;', default: '&#x22;md&#x22;', description: &#x22;Bar height: 6px or 8px.&#x22; },
  segments: { type: &#x22;number&#x22;, description: &#x22;Splits the bar into this many segments.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name when there is no visible label.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of an element that labels the meter.&#x22; },
  className: { type: &#x22;string | ((state: MeterRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`Meter`](https://react-aria.adobe.com/Meter#api), such as `id`, `style` and `aria-describedby`.

## Related

* [Progress Bar](/docs/components/progress-bar) — the progress of a running task.
* [Alert](/docs/components/alert) — pair a meter with a warning when a limit is close.
* [Badge](/docs/components/badge) — a compact status next to a reading.

---

# Progress Circle

Source: https://desyne.dev/docs/components/progress-circle

> Circular progress on React Aria's ProgressBar. Determinate or indeterminate, in four sizes and seven colors, with the value, your own text or an icon in the middle of the ring. Respects reduced motion.

```tsx title="progress-circle/demo.tsx"
"use client";

import { useEffect, useState } from "react";
import { ProgressCircle } from "@/components/ui/progress-circle";

export default function ProgressCircleDemo() {
  const [value, setValue] = useState(18);
  useEffect(() => {
    const id = setInterval(
      () => setValue((v) => (v >= 100 ? 0 : Math.min(100, v + 7))),
      700,
    );
    return () => clearInterval(id);
  }, []);
  return (
    <div className="flex items-center gap-6">
      <ProgressCircle aria-label="Uploading photos" value={value} size="lg" />
      <ProgressCircle aria-label="Syncing" isIndeterminate />
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/progress-circle
```

npm dependencies (installed by the CLI): react-aria-components.

## Usage

```tsx
import { ProgressCircle } from "@/components/ui/progress-circle";
```

```tsx
<ProgressCircle aria-label="Uploading photos" value={64} />

<ProgressCircle aria-label="Syncing" isIndeterminate />
```

<Callout title="Also exported from progress-bar">
  `ProgressCircle` used to live in `progress-bar.tsx`, which still re-exports
  it, so existing `@/components/ui/progress-bar` imports keep working.
</Callout>

### When to use

* Progress Circle: progress in a compact or square space, such as cards, dashboards, avatars and buttons, or a goal shown as a ring.
* [Progress Bar](/docs/components/progress-bar): progress with a visible label in forms, lists and dialogs.
* [Meter](/docs/components/meter): a level within a range that isn't a task (storage, quota).
* [Spinner](/docs/components/spinner): plain waiting with no progress to report.

## Anatomy

```tsx
<ProgressCircle>            {/* role="progressbar" */}
  {/* svg: track circle + fill circle (aria-hidden) */}
  {/* center: value text or children */}
</ProgressCircle>
```

| Part             | Renders                    | Notes                                                                                                  |
| ---------------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `ProgressCircle` | `<div role="progressbar">` | React Aria `ProgressBar`. Sets `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`. |
| Ring             | `<svg aria-hidden>`        | Track at 15% tone, fill drawn with `stroke-dashoffset` (500ms transition). Spins when indeterminate.   |
| Center           | `<span>`                   | The formatted value (`md` and up), or `children` when passed.                                          |

## Examples

### Sizes

`sm` (20px) for inline status next to text, `md` (48px, default), `lg` (80px) and `xl` (120px) for dashboards. The value is shown from `md` up. `strokeWidth` overrides the ring thickness.

Example `progress-circle/sizes`: source in https://desyne.dev/docs/components/progress-circle.md

### Indeterminate

`isIndeterminate` spins a quarter ring and hides the value. With reduced motion, it pulses instead of spinning.

Example `progress-circle/indeterminate`: source in https://desyne.dev/docs/components/progress-circle.md

### Colors

`color` takes any tone; the track uses the same tone at 15%.

Example `progress-circle/colors`: source in https://desyne.dev/docs/components/progress-circle.md

### Custom center content

`children` replaces the value in the middle of the ring. Pass a function to read the render props (`percentage`, `valueText`, `isIndeterminate`). Set `valueLabel` so screen readers hear the same thing you show.

Example `progress-circle/custom-content`: source in https://desyne.dev/docs/components/progress-circle.md

## Recipes

### Goals

Small circles next to text, each labelled by its heading with `aria-labelledby`, and `maxValue` set to the goal so the ring maps to real units.

Example `progress-circle/recipe-goals`: source in https://desyne.dev/docs/components/progress-circle.md

## Accessibility

* Renders `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and `aria-valuetext`. Indeterminate circles omit the value.
* There's no `label` prop, so always pass `aria-label` or `aria-labelledby`.
* `aria-valuetext` is your `valueLabel`, or the value formatted with `formatOptions`. Custom center content is visual only, so keep `valueLabel` in sync with it.
* The SVG is `aria-hidden`.
* Respects `prefers-reduced-motion`: the fill jumps to each value, and the indeterminate ring pulses instead of spinning.
* Progress circles aren't live regions. To announce completion, update a `role="status"` element.

## Styling

### Data slots

| Slot                                | Element        |
| ----------------------------------- | -------------- |
| `data-slot="progress-circle"`       | Root           |
| `data-slot="progress-circle-label"` | Center content |

### Tone variables

`color` sets `--tone` on the root. The track uses `stroke-(--tone)/15` and the fill `stroke-(--tone)`.

## API Reference

<TypeTable
  type="{
  value: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Current value.&#x22; },
  minValue: { type: &#x22;number&#x22;, default: &#x22;0&#x22;, description: &#x22;Start of the range.&#x22; },
  maxValue: { type: &#x22;number&#x22;, default: &#x22;100&#x22;, description: &#x22;End of the range.&#x22; },
  isIndeterminate: { type: &#x22;boolean&#x22;, description: &#x22;Spinning ring with no value.&#x22; },
  size: { type: '&#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22; | &#x22;xl&#x22;', default: '&#x22;md&#x22;', description: &#x22;Diameter: 20, 48, 80 or 120px.&#x22; },
  strokeWidth: { type: &#x22;number&#x22;, description: &#x22;Ring thickness in px. Defaults to 3, 4, 6 or 8 by size.&#x22; },
  color: { type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;', default: '&#x22;brand&#x22;', description: &#x22;Tone of the ring.&#x22; },
  showValue: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;Shows the value text in the middle (md and up).&#x22; },
  children: { type: &#x22;ReactNode | ((values: ProgressBarRenderProps) => ReactNode)&#x22;, description: &#x22;Custom center content, replacing the value.&#x22; },
  valueLabel: { type: &#x22;ReactNode&#x22;, description: &#x22;Replaces the formatted value. Also used as aria-valuetext, so prefer a string.&#x22; },
  formatOptions: { type: &#x22;Intl.NumberFormatOptions&#x22;, default: &#x22;{ style: 'percent' }&#x22;, description: &#x22;How the value is formatted.&#x22; },
  &#x22;aria-label&#x22;: { type: &#x22;string&#x22;, description: &#x22;Accessible name.&#x22; },
  &#x22;aria-labelledby&#x22;: { type: &#x22;string&#x22;, description: &#x22;Id of an element that labels the circle.&#x22; },
  className: { type: &#x22;string | ((state: ProgressBarRenderProps) => string)&#x22;, description: &#x22;Classes, or a function of the render state.&#x22; },
}"
/>

Also accepts every prop of React Aria's [`ProgressBar`](https://react-aria.adobe.com/ProgressBar#api).

## Related

* [Progress Bar](/docs/components/progress-bar): the same information as a bar, with a label.
* [Spinner](/docs/components/spinner): waiting without progress.
* [Meter](/docs/components/meter): a level within a range.

---

# Skeleton

Source: https://desyne.dev/docs/components/skeleton

> A placeholder that mirrors the shape of content while it loads, so the layout doesn't jump when data arrives. Any size or shape via classes, with pulse, shimmer or static animation.

```tsx title="skeleton/demo.tsx"
"use client";

import { Skeleton } from "@/components/ui/skeleton";

export default function SkeletonDemo() {
  return (
    <div className="flex items-center gap-4">
      <Skeleton className="size-12 rounded-full" />
      <div className="space-y-2">
        <Skeleton className="h-4 w-56" />
        <Skeleton className="h-4 w-40" />
      </div>
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/skeleton
```

## Usage

```tsx
import { Skeleton } from "@/components/ui/skeleton";
```

```tsx
<Skeleton className="h-4 w-48" />
```

A skeleton is an empty, rounded, muted `<div>`. Give it the size of the content it stands in for with `h-*`, `w-*` or `size-*`, and change the shape with `rounded-*`.

<Callout title="Shimmer keyframes">
  `animation="shimmer"` uses the `animate-shimmer` keyframes from the theme
  CSS, which the registry adds on install. `pulse` uses Tailwind's built-in
  `animate-pulse`.
</Callout>

### When to use

* Skeleton — the layout of the incoming content is known (a card, a list, a table) and loading takes long enough to notice.
* [Spinner](/docs/components/spinner) — a short wait in a small space, or when you can't predict the shape of the result.
* [Progress Bar](/docs/components/progress-bar) — a long task with measurable progress.
* Show nothing for waits under \~300ms; a flash of placeholders feels slower than a brief pause.

## Anatomy

A skeleton is a single element. Compose several to sketch the content they replace.

```tsx
<div aria-busy="true">            {/* the region that is loading */}
  <Skeleton className="size-10 rounded-full" />   {/* avatar */}
  <Skeleton className="h-4 w-32" />               {/* text line */}
</div>
```

| Part              | Renders             | Notes                                                                                            |
| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `Skeleton`        | `<div aria-hidden>` | `rounded-md bg-muted` plus the animation. Carries `data-slot="skeleton"`. Server-component safe. |
| Shimmer highlight | `::before`          | A gradient that sweeps across when `animation="shimmer"`.                                        |

## Examples

### Shapes

Match the real element's dimensions: `rounded-full` for avatars and pills, `rounded-lg` for thumbnails and media, the default `rounded-md` for text and buttons.

Example `skeleton/shapes`: source in https://desyne.dev/docs/components/skeleton.md

### Animation

`pulse` (default) fades the placeholder in and out. `shimmer` sweeps a soft highlight across, which reads well on large media blocks. `none` is static, for dense screens with many placeholders. Under `prefers-reduced-motion`, `pulse` and `shimmer` fall back to the static block automatically.

Example `skeleton/animations`: source in https://desyne.dev/docs/components/skeleton.md

### Text

Vary line widths and end on a shorter line so a block reads as a paragraph rather than a grid of bars.

Example `skeleton/text`: source in https://desyne.dev/docs/components/skeleton.md

### List

Repeat a row template for lists. A few rows are enough to suggest the content; you don't need to match the final count.

Example `skeleton/list`: source in https://desyne.dev/docs/components/skeleton.md

### Inline values

For values inside text, make the skeleton `inline-block` and size it to the line with `h-[1lh]` or `h-[1em]`, so the surrounding text doesn't shift when the value arrives.

Example `skeleton/inline`: source in https://desyne.dev/docs/components/skeleton.md

### Swapping in content

Render skeletons while loading and the real content once it's ready, keeping the container the same. Mark the container with `aria-busy` while it loads.

Example `skeleton/loading-state`: source in https://desyne.dev/docs/components/skeleton.md

## Recipes

### Table rows

Keep the [`Table`](/docs/components/table) header and swap each row's cells for skeletons of similar width. Cells get a `textValue` so the table stays valid while loading.

Example `skeleton/recipe-table`: source in https://desyne.dev/docs/components/skeleton.md

### Dashboard stats

Static labels stay visible while only the numbers load, inside [`Card`](/docs/components/card)s. Sizing each skeleton to the line height of the final text avoids layout shift.

Example `skeleton/recipe-stats`: source in https://desyne.dev/docs/components/skeleton.md

### Media grid

A grid of shimmering thumbnails with author and title lines, for galleries and template pickers.

Example `skeleton/recipe-media-grid`: source in https://desyne.dev/docs/components/skeleton.md

## Accessibility

* Every skeleton is `aria-hidden`, so placeholders are never read out.
* Put `aria-busy="true"` on the region that is loading and remove it when content arrives. Give the region a label (or keep a visible heading) so users know what is loading.
* If users need to know when loading finishes, announce it with a live region (`aria-live="polite"`) or a [toast](/docs/components/toast).
* Respects `prefers-reduced-motion`: the pulse stops (`motion-reduce:animate-none`) and the shimmer highlight is removed (`motion-reduce:before:hidden`), leaving a static `bg-muted` block with the same shape, so the loading layout stays clear without motion.

## Styling

### Data slots

| Slot                   | Element        |
| ---------------------- | -------------- |
| `data-slot="skeleton"` | Every skeleton |

### Customizing

* Size and shape come entirely from `className`: `h-*`, `w-*`, `size-*`, `aspect-*` and `rounded-*`.
* Change the color with a background class, e.g. `bg-foreground/10` on muted surfaces.
* The shimmer highlight is `via-foreground/[0.06]` on the `::before` element; override it with `before:via-…`.

## API Reference

### Skeleton

<TypeTable
  type="{
  animation: {
    type: '&#x22;pulse&#x22; | &#x22;shimmer&#x22; | &#x22;none&#x22;',
    default: '&#x22;pulse&#x22;',
    description: &#x22;pulse fades in and out; shimmer sweeps a highlight across; none is static. pulse and shimmer become static under prefers-reduced-motion.&#x22;,
  },
  className: { type: &#x22;string&#x22;, description: &#x22;Size, shape and color classes, merged with tailwind-merge.&#x22; },
}"
/>

Also accepts every prop of `<div>`. `aria-hidden` is set by default.

## Related

* [Spinner](/docs/components/spinner) — a compact loading indicator.
* [Progress Bar](/docs/components/progress-bar) — measurable progress for long tasks.
* [Card](/docs/components/card) and [Table](/docs/components/table) — common containers for skeleton layouts.

---

# Spinner

Source: https://desyne.dev/docs/components/spinner

> A compact, indeterminate loading indicator for short waits. Four sizes, inherits the current text color or takes a tone, and exposes an accessible status label. Server-component safe.

```tsx title="spinner/demo.tsx"
"use client";

import { Spinner } from "@/components/ui/spinner";

export default function SpinnerDemo() {
  return (
    <div className="flex items-center gap-2 text-muted-foreground text-sm">
      <Spinner aria-hidden />
      Loading your workspace…
    </div>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/spinner
```

npm dependencies (installed by the CLI): tailwind-variants.

## Usage

```tsx
import { Spinner } from "@/components/ui/spinner";
```

```tsx
<Spinner label="Loading invoices" />
```

<Callout title="Buttons have their own spinner">
  For a button that is working, use [`Button`](/docs/components/button)'s
  `isPending` prop instead of placing a `Spinner` inside it. It shows a spinner,
  blocks presses and announces the busy state for you.
</Callout>

### When to use

* Spinner — a short wait (roughly under a few seconds) with no measurable progress, in a small space: inline text, badges, list footers, a refreshing panel.
* [Skeleton](/docs/components/skeleton) — when you know the shape of the content that's loading; it avoids layout shift.
* [Progress Bar](/docs/components/progress-bar) — when you can measure progress, or the wait is long enough that users need to know how far along it is.
* [Toast](/docs/components/toast) with `toast.promise` — for background work the user shouldn't wait on.

## Anatomy

A spinner is a single element: a bordered circle with one transparent side, rotating.

```tsx
<Spinner />   {/* <span role="status" aria-label="Loading"> */}
```

| Part      | Renders                | Notes                                                                                                                                       |
| --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `Spinner` | `<span role="status">` | Root. `border-current` with a transparent right edge, `animate-spin` (`animate-pulse` under reduced motion). Carries `data-slot="spinner"`. |

## Examples

### Sizes

`sm` (16px) is the default and matches body text. `xs` (12px) fits badges and small buttons, `md` (20px) suits headings and toolbars, and `lg` (32px) is for panels and page-level loading.

Example `spinner/sizes`: source in https://desyne.dev/docs/components/spinner.md

### Colors

Without `color`, the spinner uses the current text color, so it blends into whatever it's placed in. Pass a tone to give it its own color.

Example `spinner/colors`: source in https://desyne.dev/docs/components/spinner.md

### Custom size

For sizes outside the scale, set `size-*` and a matching border width with `className`. Tailwind's arbitrary properties can also slow the rotation.

Example `spinner/custom-size`: source in https://desyne.dev/docs/components/spinner.md

### Label

`label` ("Loading" by default) becomes the accessible name. Make it specific when the spinner stands alone. When visible text next to it already says what's happening, pass `aria-hidden` so screen readers don't hear it twice.

Example `spinner/label`: source in https://desyne.dev/docs/components/spinner.md

### In context

Spinners inherit the text color and don't shrink in flex rows, so they drop into [badges](/docs/components/badge) and inline status text without extra styling.

Example `spinner/in-context`: source in https://desyne.dev/docs/components/spinner.md

### Loading overlay

Cover stale content with a translucent layer and a centered spinner while it refreshes. Keep the old content visible underneath so the layout doesn't jump.

Example `spinner/overlay`: source in https://desyne.dev/docs/components/spinner.md

## Recipes

### Deploy steps

A step list where the running step shows a spinner and finished steps show a check. A visually hidden live region announces each step, since the spinners are hidden from screen readers.

Example `spinner/recipe-deploy-steps`: source in https://desyne.dev/docs/components/spinner.md

### Load more

A list footer that swaps its button for a spinner and text while the next page loads.

Example `spinner/recipe-load-more`: source in https://desyne.dev/docs/components/spinner.md

## Accessibility

* Renders `role="status"` with `aria-label` set from `label`, so it's exposed as a named status element.
* Give standalone spinners a specific `label` ("Loading invoices"). Next to visible text, pass `aria-hidden` instead.
* A spinner that appears doesn't reliably announce itself. If completion matters, announce it with a live region or a [toast](/docs/components/toast), and set `aria-busy` on the region that is loading.
* Respects `prefers-reduced-motion`: the ring stops rotating and fades gently in and out instead (`motion-reduce:animate-pulse`), so it still reads as "working" without movement. The `role="status"` label is announced either way. Add `motion-reduce:animate-none` to a spinner's `className` for a fully static ring.

## Styling

### Data slots

| Slot                  | Element |
| --------------------- | ------- |
| `data-slot="spinner"` | Root    |

### Customizing

* Color comes from `currentColor`, so `text-*` classes on the spinner or any parent recolor it. `color` sets the `--tone` variable and applies `text-(--tone)`.
* Size comes from `size-*` and the ring thickness from `border-*` (2px by default, 1.5px at `xs`, 3px at `lg`).
* The spinner is a plain `<span>` with no client-side JavaScript, so it can render in server components.

## API Reference

### Spinner

<TypeTable
  type="{
  size: { type: '&#x22;xs&#x22; | &#x22;sm&#x22; | &#x22;md&#x22; | &#x22;lg&#x22;', default: '&#x22;sm&#x22;', description: &#x22;12px, 16px, 20px or 32px.&#x22; },
  color: {
    type: '&#x22;primary&#x22; | &#x22;brand&#x22; | &#x22;neutral&#x22; | &#x22;danger&#x22; | &#x22;success&#x22; | &#x22;warning&#x22; | &#x22;info&#x22;',
    description: &#x22;Tone of the ring. Defaults to the current text color.&#x22;,
  },
  label: { type: &#x22;string&#x22;, default: '&#x22;Loading&#x22;', description: &#x22;Accessible name (aria-label).&#x22; },
  className: { type: &#x22;string&#x22;, description: &#x22;Extra classes, merged with tailwind-merge.&#x22; },
}"
/>

Also accepts every prop of `<span>`, such as `aria-hidden`.

## Related

* [Button](/docs/components/button) — `isPending` for buttons that are working.
* [Skeleton](/docs/components/skeleton) — placeholders that match the incoming layout.
* [Progress Bar](/docs/components/progress-bar) — measurable or long-running progress, including `ProgressCircle`.

---

# Toast

Source: https://desyne.dev/docs/components/toast

> Brief, non-blocking notifications that stack in a corner of the screen, powered by sonner. Typed toasts with themed icons, descriptions, actions, promise and loading states, in-place updates, custom content and six positions.

```tsx title="toast/demo.tsx"
"use client";

import { Button } from "@/components/ui/button";
import { toast } from "@/components/ui/toast";

// <Toaster /> is mounted once in the root layout — see Usage.
export default function ToastDemo() {
  return (
    <Button
      variant="outline"
      onPress={() =>
        toast("Event created", {
          description: "Design review · Friday, June 14 at 10:00 AM",
          action: { label: "Undo", onClick: () => toast("Event removed") },
        })
      }
    >
      Show toast
    </Button>
  );
}
```

## Installation

```bash
npx shadcn@latest add @desyne/toast
```

npm dependencies (installed by the CLI): lucide-react, sonner.

## Usage

Mount `<Toaster />` once, near the root of your app:

```tsx
// app/layout.tsx
import { Toaster } from "@/components/ui/toast";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toaster />
      </body>
    </html>
  );
}
```

Then call `toast()` from anywhere — event handlers, effects, even outside React:

```tsx
import { toast } from "@/components/ui/toast";

toast.success("Changes saved");
```

<Callout title="One Toaster per app">
  Toasts only appear where a `<Toaster />` is mounted, and every mounted
  `<Toaster />` without an `id` renders every toast, so two of them show
  duplicates. Mount it once in the root layout, not inside pages or dialogs.
</Callout>

### When to use

* Toast — short feedback about something that just happened ("Saved", "Invite sent", "Deploy failed"), or background work the user doesn't have to wait on.
* [Alert](/docs/components/alert) — a message that belongs to the page and must stay visible until the situation changes, such as a form error or a billing problem.
* [Dialog](/docs/components/dialog) — when the user must respond before continuing.
* Don't put the only way to do something in a toast; it disappears. Actions like "Undo" should be shortcuts for something also reachable elsewhere.

## Anatomy

```tsx
<Toaster />                      {/* <section aria-live="polite"> › <ol> per position */}

toast(title, {
  icon,                          // leading icon (typed toasts get one by default)
  description,                   // secondary line
  action,                        // primary button
  cancel,                        // secondary button
});
```

| Part            | Renders                             | Notes                                                                                                                                 |
| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Toaster`       | `<section>` › `<ol>`                | The live region and one list per position in use. Themed with popover tokens.                                                         |
| Toast           | `<li data-sonner-toast>`            | One notification. Carries `data-type` (`success`, `error`, …).                                                                        |
| Icon            | `<div data-icon>`                   | Lucide icon per type; tinted with the matching status color.                                                                          |
| Title           | `<div data-title>`                  | The first argument to `toast()`.                                                                                                      |
| Description     | `<div data-description>`            | Muted secondary text.                                                                                                                 |
| Action / Cancel | `<button>`                          | From `action` and `cancel`. The action closes the toast unless its `onClick` calls `event.preventDefault()`; cancel always closes it. |
| Close button    | `<button aria-label="Close toast">` | Shown when `closeButton` is set on the toast or the Toaster. Never shown on loading or custom toasts.                                 |

## Examples

### Types

`toast()` shows a plain message. `toast.success`, `toast.info`, `toast.warning` and `toast.error` add a tinted icon that matches the status colors of the rest of the library.

Example `toast/types`: source in https://desyne.dev/docs/components/toast.md

### Description

`description` adds a muted second line for detail that doesn't fit the title. Keep the title short enough to scan.

Example `toast/description`: source in https://desyne.dev/docs/components/toast.md

### Actions

`action` renders a primary button, `cancel` a secondary one. Both take a `label` and an `onClick`, and close the toast after running. Use them for quick follow-ups like "Undo" or "View".

Example `toast/action`: source in https://desyne.dev/docs/components/toast.md

### Promise

`toast.promise` shows a loading toast, then replaces it with the result. `success` and `error` can be functions that receive the resolved value or the rejection reason.

Example `toast/promise`: source in https://desyne.dev/docs/components/toast.md

### Updating a toast

Every call returns an id. Pass it back as `id` to update the same toast in place — for example, to walk a `toast.loading` toast through several steps before it succeeds.

Example `toast/update`: source in https://desyne.dev/docs/components/toast.md

### Dismissing

`toast.dismiss(id)` closes one toast; `toast.dismiss()` closes them all. Use it for toasts that track a state the user can end elsewhere.

Example `toast/dismiss`: source in https://desyne.dev/docs/components/toast.md

### Duration and close button

Toasts close after 4 seconds by default. Shorten `duration` for trivial confirmations, lengthen it for anything with text to read, and use `Infinity` with `closeButton` for ongoing states. Timers pause while the user hovers the stack or the tab is hidden.

Example `toast/duration`: source in https://desyne.dev/docs/components/toast.md

### Custom icon

`icon` replaces the default icon, and adds one to plain toasts. Size it with `size-4` to match the built-in icons.

Example `toast/icon`: source in https://desyne.dev/docs/components/toast.md

### Rich colors

`richColors: true` tints the whole toast with sonner's success, info, warning and error palettes. Set it on the `<Toaster />` to apply it to every toast. The palettes switch to their dark variants automatically when your app is in dark mode (see [Color mode](#color-mode)); toggle the docs theme to compare.

Example `toast/rich-colors`: source in https://desyne.dev/docs/components/toast.md

### Position

The Toaster's `position` (default `bottom-right`) sets where toasts appear. Individual toasts can override it with their own `position`.

Example `toast/position`: source in https://desyne.dev/docs/components/toast.md

### Custom content

`toast.custom` renders your own JSX and keeps sonner's stacking, timing and swipe-to-dismiss. The render function receives the toast's id so buttons inside can dismiss it.

Example `toast/custom`: source in https://desyne.dev/docs/components/toast.md

## Recipes

### Save with toast.promise

Submit a form, keep the button pending until the promise settles, and let `toast.promise` report success or the server's error message. `finally` resets the button either way.

Example `toast/recipe-save-form`: source in https://desyne.dev/docs/components/toast.md

### Delete with undo

Remove the item from the list right away and offer "Undo" in the toast. Commit the delete in `onAutoClose`, once the undo window has passed.

Example `toast/recipe-undo-delete`: source in https://desyne.dev/docs/components/toast.md

### Export progress

A custom toast with a [`ProgressBar`](/docs/components/progress-bar), re-rendered through the same id as the export runs, then swapped for a success toast with a download action.

Example `toast/recipe-export-progress`: source in https://desyne.dev/docs/components/toast.md

## Accessibility

* The Toaster renders a `<section>` with `aria-live="polite"`, so new toasts are announced without interrupting and without moving focus.
* The region is labelled "Notifications" plus the hotkey. Press <kbd>Alt</kbd>+<kbd>T</kbd> to expand the stack and move focus into it; each toast is focusable.
* Timers pause while the stack is expanded (hovered, or opened with the hotkey), while a toast is being pressed or swiped, and while the page is hidden.
* sonner disables its own transitions and animations under `prefers-reduced-motion`, and the Lucide loading icon stops spinning (`motion-reduce:animate-none`).
* Toasts disappear. Keep messages short, give important ones a longer `duration`, and never make a toast the only way to reach an action.
* For errors that block the user, prefer an [Alert](/docs/components/alert) near the cause, or pair the toast with one.

### Keyboard

| Key                                              | Action                                                                  |
| ------------------------------------------------ | ----------------------------------------------------------------------- |
| <kbd>Alt</kbd>+<kbd>T</kbd>                      | Expands the toasts and moves focus to them (configurable with `hotkey`) |
| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between toasts and their buttons                                  |
| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused action, cancel or close button                    |
| <kbd>Esc</kbd>                                   | Collapses the expanded stack when focus is inside it                    |

## Styling

### Theme

`Toaster` maps sonner's colors to your tokens: `--normal-bg` is `--popover`, `--normal-text` is `--popover-foreground`, `--normal-border` is `--border` and `--border-radius` is `--radius`. It also sets `toastOptions.classNames` for the toast shadow, muted descriptions, primary action buttons, muted cancel buttons and per-type icon colors, and replaces the icons with Lucide ones.

Your props are merged with these defaults instead of replacing them:

| Prop           | How it merges                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className`    | Joined with the built-in `toaster group` classes (tailwind-merge).                                                                                             |
| `style`        | Shallow-merged over the token variables, so you can override one, such as `--width`, and keep the rest.                                                        |
| `icons`        | Merged per type. Passing only `success` keeps the Lucide info, warning, error and loading icons.                                                               |
| `toastOptions` | Every option is passed through; `toastOptions.classNames` is merged key by key with `cn`, so your `toast` or `actionButton` classes are added to the defaults. |

```tsx
<Toaster
  icons={{ success: <PartyPopperIcon className="size-4" /> }}
  toastOptions={{ classNames: { title: "!font-semibold" } }}
  style={{ "--width": "420px" } as React.CSSProperties}
/>
```

sonner's own styles aren't in a cascade layer, so the defaults use the `!` (important) modifier. Use `!` on your classes too when they need to beat a sonner style or a default, for example `!bg-card`.

### Color mode

sonner's `richColors` and `invert` palettes depend on its `theme`. By default `Toaster` follows the `.dark` class on `<html>`, the same switch the theme tokens use, and watches it with a `MutationObserver`, so toasts change palette the moment your theme toggle runs. This works with next-themes (`attribute="class"`), fumadocs and hand-rolled toggles alike, and adds no dependency. During server rendering and hydration it uses `"light"`, then switches after hydration.

Pass `theme` to take over: `"light"` or `"dark"` to pin it, or `"system"` to follow `prefers-color-scheme` instead of the class (useful if your app themes with media queries rather than `.dark`).

### Custom toasts

`toast.custom` content still receives the `toast` classes (border, radius and shadow) on its `<li>`, but no background, padding or width. Give your root element `bg-popover`, padding and `w-(--width)` (356px by default).

### Per-toast classes

Every toast accepts `className`, `classNames` (with keys such as `title`, `description`, `actionButton`, `icon`) and `style`, merged with the Toaster's defaults.

## API Reference

### Toaster

<TypeTable
  type="{
  position: {
    type: '&#x22;top-left&#x22; | &#x22;top-center&#x22; | &#x22;top-right&#x22; | &#x22;bottom-left&#x22; | &#x22;bottom-center&#x22; | &#x22;bottom-right&#x22;',
    default: '&#x22;bottom-right&#x22;',
    description: &#x22;Where toasts appear.&#x22;,
  },
  duration: { type: &#x22;number&#x22;, default: &#x22;4000&#x22;, description: &#x22;Default time in ms before a toast closes.&#x22; },
  visibleToasts: { type: &#x22;number&#x22;, default: &#x22;3&#x22;, description: &#x22;How many toasts are visible in the stack.&#x22; },
  expand: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Always show the stack expanded instead of collapsed.&#x22; },
  gap: { type: &#x22;number&#x22;, default: &#x22;14&#x22;, description: &#x22;Gap in px between expanded toasts.&#x22; },
  closeButton: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Adds a close button to every toast.&#x22; },
  richColors: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Tints every typed toast with its status palette.&#x22; },
  theme: { type: '&#x22;light&#x22; | &#x22;dark&#x22; | &#x22;system&#x22;', default: &#x22;follows .dark on <html>&#x22;, description: &#x22;Color scheme used by sonner's built-in palettes. See Color mode.&#x22; },
  invert: { type: &#x22;boolean&#x22;, default: &#x22;false&#x22;, description: &#x22;Inverts the colors of every toast.&#x22; },
  offset: { type: &#x22;string | number | { top?, right?, bottom?, left? }&#x22;, default: '&#x22;24px&#x22;', description: &#x22;Distance from the viewport edges.&#x22; },
  mobileOffset: { type: &#x22;string | number | { top?, right?, bottom?, left? }&#x22;, default: '&#x22;16px&#x22;', description: &#x22;Offset on screens up to 600px wide.&#x22; },
  hotkey: { type: &#x22;string[]&#x22;, default: '[&#x22;altKey&#x22;, &#x22;KeyT&#x22;]', description: &#x22;Keys that expand and focus the toasts.&#x22; },
  swipeDirections: { type: '(&#x22;top&#x22; | &#x22;right&#x22; | &#x22;bottom&#x22; | &#x22;left&#x22;)[]', description: &#x22;Directions a toast can be swiped away. Derived from position by default.&#x22; },
  dir: { type: '&#x22;ltr&#x22; | &#x22;rtl&#x22; | &#x22;auto&#x22;', description: &#x22;Text direction. Read from the document by default.&#x22; },
  id: { type: &#x22;string&#x22;, description: &#x22;Only render toasts created with a matching toasterId.&#x22; },
  containerAriaLabel: { type: &#x22;string&#x22;, default: '&#x22;Notifications&#x22;', description: &#x22;Label of the live region (the hotkey is appended).&#x22; },
  customAriaLabel: { type: &#x22;string&#x22;, description: &#x22;Replaces the whole live region label.&#x22; },
  toastOptions: { type: &#x22;ToastOptions&#x22;, description: &#x22;Defaults for every toast. classNames are merged key by key with the built-in ones (see Styling).&#x22; },
  icons: { type: &#x22;ToastIcons&#x22;, description: &#x22;Icons per type, merged over the built-in Lucide icons.&#x22; },
  className: { type: &#x22;string&#x22;, description: 'Classes on each list, merged with the built-in &#x22;toaster group&#x22;.' },
  style: { type: &#x22;CSSProperties&#x22;, description: &#x22;Inline styles on each list, merged over the token mapping.&#x22; },
}"
/>

### toast()

```tsx
toast(message, options?)          // plain
toast.success(message, options?)  // .info, .warning, .error, .loading, .message
toast.promise(promise, { loading, success, error, description?, finally? })
toast.custom((id) => <JSX />, options?)
toast.dismiss(id?)                // one toast, or all of them
```

Every call except `dismiss` returns the toast's id. `toast.promise` returns an object with `unwrap()`, which resolves or rejects with the original promise.

<TypeTable
  type="{
  id: { type: &#x22;string | number&#x22;, description: &#x22;Reuse an id to update an existing toast in place.&#x22; },
  description: { type: &#x22;ReactNode | (() => ReactNode)&#x22;, description: &#x22;Secondary text under the title.&#x22; },
  icon: { type: &#x22;ReactNode&#x22;, description: &#x22;Replaces the type's icon, or adds one to a plain toast.&#x22; },
  action: { type: &#x22;{ label: ReactNode; onClick: (event) => void } | ReactNode&#x22;, description: &#x22;Primary button. Closes the toast unless onClick calls event.preventDefault().&#x22; },
  cancel: { type: &#x22;{ label: ReactNode; onClick: (event) => void } | ReactNode&#x22;, description: &#x22;Secondary button. Closes the toast after onClick.&#x22; },
  duration: { type: &#x22;number&#x22;, default: &#x22;4000&#x22;, description: &#x22;Time in ms before it closes. Infinity keeps it open. Loading toasts never close on their own.&#x22; },
  closeButton: { type: &#x22;boolean&#x22;, description: &#x22;Shows a close button on this toast.&#x22; },
  dismissible: { type: &#x22;boolean&#x22;, default: &#x22;true&#x22;, description: &#x22;When false, the toast can't be swiped or closed by the user.&#x22; },
  position: { type: &#x22;Position&#x22;, description: &#x22;Overrides the Toaster's position for this toast.&#x22; },
  richColors: { type: &#x22;boolean&#x22;, description: &#x22;Tints this toast with its status palette.&#x22; },
  invert: { type: &#x22;boolean&#x22;, description: &#x22;Inverts this toast's colors.&#x22; },
  onDismiss: { type: &#x22;(toast: ToastT) => void&#x22;, description: &#x22;Called when the user closes or swipes the toast, or it's dismissed programmatically.&#x22; },
  onAutoClose: { type: &#x22;(toast: ToastT) => void&#x22;, description: &#x22;Called when the toast closes because its timer ran out.&#x22; },
  toasterId: { type: &#x22;string&#x22;, description: &#x22;Send the toast to the Toaster with this id.&#x22; },
  className: { type: &#x22;string&#x22; },
  classNames: { type: &#x22;ToastClassnames&#x22;, description: &#x22;Classes for the toast's parts (title, description, actionButton, icon, …).&#x22; },
  style: { type: &#x22;CSSProperties&#x22; },
  unstyled: { type: &#x22;boolean&#x22;, description: &#x22;Removes sonner's default styles from this toast.&#x22; },
}"
/>

### toast.promise

<TypeTable
  type="{
  loading: { type: &#x22;ReactNode&#x22;, description: &#x22;Shown while the promise is pending.&#x22; },
  success: { type: &#x22;ReactNode | ((data) => ReactNode | { message, ...options })&#x22;, description: &#x22;Shown when it resolves. Return an object to also set description, action and so on.&#x22; },
  error: { type: &#x22;ReactNode | ((error) => ReactNode | { message, ...options })&#x22;, description: &#x22;Shown when it rejects.&#x22; },
  description: { type: &#x22;ReactNode | ((dataOrError) => ReactNode)&#x22;, description: &#x22;Description for every state.&#x22; },
  finally: { type: &#x22;() => void | Promise<void>&#x22;, description: &#x22;Runs after the promise settles either way.&#x22; },
}"
/>

Also accepts every `toast()` option except `description`, which takes the form above. See the [sonner docs](https://sonner.emilkowal.ski) for the full reference.

## Related

* [Alert](/docs/components/alert) — persistent, in-page messages.
* [Dialog](/docs/components/dialog) — when the user must respond.
* [Progress Bar](/docs/components/progress-bar) — progress inside a custom toast.
* [Button](/docs/components/button) — `isPending` for the action that triggers the toast.